Copyright: Win32 Online Help, Version 1.00.305


Win32 API Help Contents
Win32 API Quick Reference

Visual FoxPro provides access to the Win32 API functions through the DECLARE - DLL command. DECLARE - DLL is used to register a Win32 API function in Visual FoxPro by specifying the name of the Win32 API function and the parameter types the Win32 API function expects to receive. See DECLARE - DLL for additional information about registering Win32 API functions in Visual FoxPro.

Not all Win32 API functions are supported through DECLARE - DLL. Win32 API functions that require pointers cannot be accessed through DECLARE - DLL. However, they may be accessed through the API library construction routines provided in the Professional Edition of Visual FoxPro.

Note that 16-bit DLLs can be called through FOXTOOLS.FLL.

Alphabetical Lists

Data Types

Enumeration Types

Functions

Interfaces

Macros

Messages

Structures


Win32 API Help Contents: Functions
Functions

_hread

_hwrite

_lclose

_lcreat

_llseek

_lopen

_lread

_lwrite

A

AbnormalTermination

AbortDoc

AbortPath

AbortPrinter

AbortProc

AbortSystemShutdown

accept

AccessCheck

AccessCheckAndAuditAlarm

AccessResource

AcsLan

ActivateKeyboardLayout

AddAccessAllowedAce

AddAccessDeniedAce

AddAce

AddAtom

AddAuditAccessAce

AddFontResource

AddForm

AddJob

AddMonitor

AddPort

AddPrinter

AddPrinterConnection

AddPrinterDriver

AddPrintProcessor

AddPrintProvidor

AddPropSheetPageProc  (preliminaryWindows NT)

AdjustTokenGroups

AdjustTokenPrivileges

AdjustWindowRect

AdjustWindowRectEx

AdvancedDocumentProperties

AllocateAndInitializeSid

AllocateLocallyUniqueId

AllocConsole

AllocDStoCSAlias

AllocResource

AllocSelector

AngleArc

AnimatePalette

AnsiLower

AnsiLowerBuff

AnsiNext

AnsiPrev

AnsiToOem

AnsiToOemBuff

AnsiUpper

AnsiUpperBuff

AnyPopup

AppendMenu

Arc

ArcTo

AreAllAccessesGranted

AreAnyAccessesGranted

AreFileApisANSI

ArrangeIconicWindows

AttachThreadInput

B

BackupEventLog

BackupRead

BackupSeek

BackupWrite

Beep

BeginDeferWindowPos

BeginPaint

BeginPath

BeginUpdateResource

bind

BitBlt

BringWindowToTop

BroadcastSystemMessage  (preliminaryWindows 95)

BrowseCallbackProc

BuildCommDCB

BuildCommDCBAndTimeouts

C

CallMsgFilter

CallNamedPipe

CallNextHookEx

CallWindowProc

CallWndProc

CallWndRetProc  (preliminaryWindows 95)

CancelDC

CascadeWindows  (preliminaryWindows 95)

Catch

CBTProc

ChangeClipboardChain

ChangeMenu

ChangeSelector

ChangeServiceConfig

CharLower

CharLowerBuff

CharNext

CharPrev

CharToOem

CharToOemBuff

CharUpper

CharUpperBuff

CheckColorsInGamut  (preliminaryWindows 95)

CheckDlgButton

CheckMenuItem

CheckMenuRadioItem  (preliminaryWindows 95)

CheckRadioButton

ChildWindowFromPoint

ChildWindowFromPointEx  (preliminaryWindows NT)

ChooseColor

ChooseFont

Chord

ClearCommBreak

ClearCommError

ClearEventLog

ClientToScreen

ClipCursor

CloseClipboard

CloseDesktop  (preliminaryWindows NT)

CloseEnhMetaFile

CloseEventLog

CloseFigure

CloseHandle

CloseMetaFile

ClosePrinter

CloseServiceHandle

closesocket

CloseSound

CloseWindow

CloseWindowStation  (preliminaryWindows NT)

ColorMatchToTarget  (preliminaryWindows 95)

CombineRgn

CombineTransform

CommandLineToArgvW

CommConfigDialog  (preliminaryWindows 95)

CommDlgExtendedError

CompareFileTime

CompareString

ConfigurePort

connect

ConnectNamedPipe

ConnectToPrinterDlg

ContinueDebugEvent

ControlService

ConvertDefaultLocale

CopyAcceleratorTable

CopyCursor

CopyEnhMetaFile

CopyFile

CopyIcon

CopyImage  (preliminaryWindows 95)

CopyLZFile

CopyMemory

CopyMetaFile

CopyRect

CopySid

CountClipboardFormats

CountVoiceNotes

CPlApplet

CreateAcceleratorTable

CreateBitmap

CreateBitmapIndirect

CreateBrushIndirect

CreateCaret

CreateColorSpace  (preliminaryWindows 95)

CreateCompatibleBitmap

CreateCompatibleDC

CreateConsoleScreenBuffer

CreateCursor

CreateDC

CreateDesktop  (preliminaryWindows NT)

CreateDialog

CreateDialogIndirect

CreateDialogIndirectParam

CreateDialogParam

CreateDIBitmap

CreateDIBPatternBrush

CreateDIBPatternBrushPt

CreateDIBSection

CreateDirectory

CreateDirectoryEx

CreateDiscardableBitmap

CreateEllipticRgn

CreateEllipticRgnIndirect

CreateEnhMetaFile

CreateEvent

CreateFile

CreateFileMapping

CreateFont

CreateFontIndirect

CreateHalftonePalette

CreateHatchBrush

CreateIC

CreateIcon

CreateIconFromResource

CreateIconFromResourceEx  (preliminaryWindows 95)

CreateIconIndirect

CreateIoCompletionPort

CreateMailslot

CreateMappedBitmap  (preliminaryWindows NT)

CreateMDIWindow

CreateMenu

CreateMetaFile

CreateMutex

CreateNamedPipe

CreatePalette

CreatePatternBrush

CreatePen

CreatePenIndirect

CreatePipe

CreatePolygonRgn

CreatePolyPolygonRgn

CreatePopupMenu

CreatePrivateObjectSecurity

CreateProcess

CreateProcessAsUser  (preliminaryWindows NT)

CreatePropertySheetPage  (preliminaryWindows NT)

CreateRectRgn

CreateRectRgnIndirect

CreateRemoteThread

CreateRoundRectRgn

CreateScalableFontResource

CreateSemaphore

CreateService

CreateSolidBrush

CreateStatusWindow  (preliminaryWindows NT)

CreateTapePartition

CreateToolbarEx  (preliminaryWindows NT)

CreateThread

CreateUpDownControl  (preliminaryWindows NT)

CreateWindow

CreateWindowEx

CreateWindowStation  (preliminaryWindows NT)

D

DdeAbandonTransaction

DdeAccessData

DdeAddData

DdeCallback

DdeClientTransaction

DdeCmpStringHandles

DdeConnect

DdeConnectList

DdeCreateDataHandle

DdeCreateStringHandle

DdeDisconnect

DdeDisconnectList

DdeEnableCallback

DdeFreeDataHandle

DdeFreeStringHandle

DdeGetData

DdeGetLastError

DdeImpersonateClient

DdeInitialize

DdeKeepStringHandle

DdeNameService

DdePostAdvise

DdeQueryConvInfo

DdeQueryNextServer

DdeQueryString

DdeReconnect

DdeSetQualityOfService

DdeSetUserHandle

DdeUnaccessData

DdeUninitialize

DebugActiveProcess

DebugBreak

DebugProc

DefDlgProc

DeferWindowPos

DefFrameProc

DefHookProc

DefineDosDevice

DefineHandleTable

DefMDIChildProc

DefScreenSaverProc

DefWindowProc

DeleteAce

DeleteAtom

DeleteColorSpace  (preliminaryWindows 95)

DeleteCriticalSection

DeleteDC

DeleteEnhMetaFile

DeleteFile

DeleteForm

DeleteMenu

DeleteMetaFile

DeleteMonitor

DeleteObject

DeletePort

DeletePrinter

DeletePrinterConnection

DeletePrinterDriver

DeletePrintProcessor

DeletePrintProvidor

DeleteService

DeregisterEventSource

DestroyAcceleratorTable

DestroyCaret

DestroyCursor

DestroyIcon

DestroyMenu

DestroyPrivateObjectSecurity

DestroyPropertySheetPage  (preliminaryWindows NT)

DestroyWindow

DeviceCapabilities

DeviceIoControl

DialogBox

DialogBoxIndirect

DialogBoxIndirectParam

DialogBoxParam

DialogProc

DisableThreadLibraryCalls

DisconnectNamedPipe

DispatchMessage

DlgDirList

DlgDirListComboBox

DlgDirSelect

DlgDirSelectComboBox

DlgDirSelectComboBoxEx

DlgDirSelectEx

DllEntryPoint

DocumentProperties

DOS3Call

DosDateTimeToFileTime

DPtoLP

DragAcceptFiles

DragDetect

DragFinish

DragQueryFile

DragQueryPoint

DrawAnimatedRects  (preliminaryWindows 95)

DrawCaption  (preliminaryWindows 95)

DrawEdge  (preliminaryWindows NT)

DrawEscape

DrawFocusRect

DrawFrameControl  (preliminaryWindows NT)

DrawIcon

DrawIconEx  (preliminaryWindows NT)

DrawInsert  (preliminaryWindows NT)

DrawMenuBar

DrawState  (preliminaryWindows 95)

DrawStateProc  (preliminaryWindows 95)

DrawStatusText  (preliminaryWindows NT)

DrawText

DrawTextEx  (preliminaryWindows 95)

DuplicateHandle

DuplicateToken

E

EditWordBreakProc

Ellipse

EmptyClipboard

EnableMenuItem

EnableScrollBar

EnableWindow

EndDeferWindowPos

EndDialog

EndDoc

EndDocPrinter

EndPage

EndPagePrinter

EndPaint

EndPath

EndUpdateResource

EnhMetaFileProc

EnterCriticalSection

EnumCalendarInfo

EnumCalendarInfoProc

EnumChildProc

EnumChildWindows

EnumClipboardFormats

EnumCodePagesProc

EnumDateFormats

EnumDateFormatsProc

EnumDependentServices

EnumDesktopProc  (preliminaryWindows NT)

EnumDesktops  (preliminaryWindows NT)

EnumDesktopWindows  (preliminaryWindows NT)

EnumDisplaySettings  (preliminaryWindows NT)

EnumEnhMetaFile

EnumFontFamExProc  (preliminaryWindows 95)

EnumFontFamilies

EnumFontFamiliesEx  (preliminaryWindows 95)

EnumFontFamProc

EnumFonts

EnumFontsProc

EnumForms

EnumICMProfiles  (preliminaryWindows 95)

EnumICMProfilesProc  (preliminaryWindows 95)

EnumJobs

EnumLocalesProc

EnumMetaFile

EnumMetaFileProc

EnumMonitors

EnumObjects

EnumObjectsProc

EnumPorts

EnumPrinterDrivers

EnumPrinters

EnumPrintProcessorDatatypes

EnumPrintProcessors

EnumProps

EnumPropsEx

EnumProtocols

EnumRegisterWordProc  (preliminaryWindows 95)

EnumResLangProc

EnumResNameProc

EnumResourceLanguages

EnumResourceNames

EnumResourceTypes

EnumResTypeProc

EnumServicesStatus

EnumSystemCodePages

EnumSystemLocales

EnumTaskWindows

EnumThreadWindows

EnumThreadWndProc

EnumTimeFormats

EnumTimeFormatsProc

EnumWindows

EnumWindowsProc

EnumWindowStationProc  (preliminaryWindows NT)

EnumWindowStations  (preliminaryWindows NT)

EqualPrefixSid

EqualRect

EqualRgn

EqualSid

EraseTape

Escape

EscapeCommFunction

ExcludeClipRect

ExcludeUpdateRgn

ExitProcess

ExitThread

ExitWindows

ExitWindowsEx

ExpandEnvironmentStrings

ExtCreatePen

ExtCreateRegion

ExtDeviceMode

ExtensionPropSheetPageProc  (preliminaryWindows NT)

ExtEscape

ExtFloodFill

ExtractAssociatedIcon

ExtractIcon

ExtSelectClipRgn

ExtTextOut

F

FatalAppExit

FatalExit

FileIOCompletionRoutine

FileTimeToDosDateTime

FileTimeToLocalFileTime

FileTimeToSystemTime

FillConsoleOutputAttribute

FillConsoleOutputCharacter

FillMemory

FillPath

FillRect

FillRgn

FindAtom

FindClose

FindCloseChangeNotification

FindClosePrinterChangeNotification

FindExecutable

FindFirstChangeNotification

FindFirstFile

FindFirstFreeAce

FindFirstPrinterChangeNotification

FindNextChangeNotification

FindNextFile

FindNextPrinterChangeNotification

FindResource

FindResourceEx

FindText

FindWindow

FindWindowEx  (preliminaryWindows 95)

FixBrushOrgEx

FlashWindow

FlattenPath

FloodFill

FlushConsoleInputBuffer

FlushFileBuffers

FlushInstructionCache

FlushViewOfFile

FMExtensionProc

FoldString

ForegroundIdleProc

FormatMessage

FrameRect

FrameRgn

FreeConsole

FreeDDElParam

FreeEnvironmentStrings

FreeImageColorMatcher  (preliminaryWindows 95)

FreeLibrary

FreeLibraryAndExitThread

FreeModule

FreePrinterNotifyInfo

FreeProcInstance

FreeResource

FreeSelector

FreeSid

FSCTL_DISMOUNT_VOLUME

FSCTL_GET_COMPRESSION  (preliminaryWindows NT)

FSCTL_LOCK_VOLUME

FSCTL_SET_COMPRESSION  (preliminaryWindows NT)

FSCTL_UNLOCK_VOLUME

G

GdiComment

GdiFlush

GdiGetBatchLimit

GdiSetBatchLimit

GenerateConsoleCtrlEvent

GetAce

GetAclInformation

GetACP

GetActiveWindow

GetAddressByName

GetArcDirection

GetAspectRatioFilter

GetAspectRatioFilterEx

GetAsyncKeyState

GetAtomHandle

GetAtomName

GetBinaryType

GetBitmapBits

GetBitmapDimension

GetBitmapDimensionEx

GetBkColor

GetBkMode

GetBoundsRect

GetBrushOrg

GetBrushOrgEx

GetCapture

GetCaretBlinkTime

GetCaretPos

GetCharABCWidths

GetCharABCWidthsFloat

GetCharacterPlacement  (preliminaryWindows 95)

GetCharWidth

GetCharWidth32

GetCharWidthFloat

GetClassInfo

GetClassInfoEx  (preliminaryWindows 95)

GetClassLong

GetClassName

GetClassWord

GetClientRect

GetClipboardData

GetClipboardFormatName

GetClipboardOwner

GetClipboardViewer

GetClipBox

GetClipCursor

GetClipRgn

GetCodeHandle

GetCodeInfo

GetColorAdjustment

GetColorSpace  (preliminaryWindows 95)

GetCommandLine

GetCommConfig  (preliminaryWindows 95)

GetCommMask

GetCommModemStatus

GetCommProperties

GetCommState

GetCommTimeouts

GetCompressedFileSize

GetComputerName

GetConsoleCP

GetConsoleCursorInfo

GetConsoleMode

GetConsoleOutputCP

GetConsoleScreenBufferInfo

GetConsoleTitle

GetCPInfo

GetCurrencyFormat

GetCurrentDirectory

GetCurrentObject

GetCurrentPDB

GetCurrentPosition

GetCurrentPositionEx

GetCurrentProcess

GetCurrentProcessId

GetCurrentTask

GetCurrentThread

GetCurrentThreadId

GetCurrentTime

GetCursor

GetCursorPos

GetDateFormat

GetDC

GetDCEx

GetDCOrg

GetDCOrgEx

GetDefaultCommConfig  (preliminaryWindows 95)

GetDesktopWindow

GetDeviceCaps

GetDeviceGammaRamp  (preliminaryWindows 95)

GetDialogBaseUnits

GetDIBColorTable

GetDIBits

GetDiskFreeSpace

GetDlgCtrlID

GetDlgItem

GetDlgItemInt

GetDlgItemText

GetDOSEnvironment

GetDoubleClickTime

GetDriveType

GetEffectiveClientRect  (preliminaryWindows NT)

GetEnhMetaFile

GetEnhMetaFileBits

GetEnhMetaFileDescription

GetEnhMetaFileHeader

GetEnhMetaFilePaletteEntries

GetEnvironmentStrings

GetEnvironmentVariable

GetExceptionCode

GetExceptionInformation

GetExitCodeProcess

GetExitCodeThread

GetExpandedName

GetFileAttributes

GetFileInformationByHandle

GetFileResource

GetFileResourceSize

GetFileSecurity

GetFileSize

GetFileTime

GetFileTitle

GetFileType

GetFileVersionInfo

GetFileVersionInfoSize

GetFocus

GetFontData

GetFontLanguageInfo  (preliminaryWindows 95)

GetForegroundWindow

GetForm

GetFreeSpace

GetFullPathName

GetGlyphOutline

GetGraphicsMode

GetHandleInformation  (preliminaryWindows NT)

gethostbyaddr

gethostbyname

gethostname

GetICMProfile  (preliminaryWindows 95)

GetIconInfo

GetInputState

GetInstanceData

GetJob

GetKBCodePage

GetKernelObjectSecurity

GetKerningPairs

GetKeyboardLayout  (preliminaryWindows 95)

GetKeyboardLayoutList  (preliminaryWindows 95)

GetKeyboardLayoutName

GetKeyboardState

GetKeyboardType

GetKeyNameText

GetKeyState

GetLargestConsoleWindowSize

GetLastActivePopup

GetLastError

GetLengthSid

GetLocaleInfo

GetLocalTime

GetLogColorSpace  (preliminaryWindows 95)

GetLogicalDrives

GetLogicalDriveStrings

GetMailslotInfo

GetMapMode

GetMenu

GetMenuCheckMarkDimensions

GetMenuContextHelpId  (preliminaryWindows NT)

GetMenuDefaultItem  (preliminaryWindows 95)

GetMenuItemCount

GetMenuItemID

GetMenuItemInfo  (preliminaryWindows 95)

GetMenuItemRect  (preliminaryWindows 95)

GetMenuState

GetMenuString

GetMessage

GetMessageExtraInfo

GetMessagePos

GetMessageTime

GetMetaFile

GetMetaFileBits

GetMetaFileBitsEx

GetMetaRgn

GetMiterLimit

GetModuleFileName

GetModuleHandle

GetModuleUsage

GetMsgProc

GetNameByType

GetNamedPipeHandleState

GetNamedPipeInfo

GetNearestColor

GetNearestPaletteIndex

GetNextDlgGroupItem

GetNextDlgTabItem

GetNextWindow

GetNumberFormat

GetNumberOfConsoleInputEvents

GetNumberOfConsoleMouseButtons

GetNumberOfEventLogRecords

GetObject

GetObjectType

GetOEMCP

GetOldestEventLogRecord

GetOpenClipboardWindow

GetOpenFileName

GetOutlineTextMetrics

GetOverlappedResult

GetPaletteEntries

GetParent

GetPath

getpeername

GetPixel

GetPolyFillMode

GetPrinter

GetPrinterData

GetPrinterDriver

GetPrinterDriverDirectory

GetPrintProcessorDirectory

GetPriorityClass

GetPriorityClipboardFormat

GetPrivateObjectSecurity

GetPrivateProfileInt

GetPrivateProfileSection

GetPrivateProfileSectionNames  (preliminaryWindows NT)

GetPrivateProfileString

GetPrivateProfileStruct  (preliminaryWindows NT)

GetProcAddress

GetProcessAffinityMask

GetProcessHeap

GetProcessHeaps

GetProcessShutdownParameters

GetProcessTimes

GetProcessVersion  (preliminaryWindows NT)

GetProcessWindowStation

GetProcessWorkingSetSize

GetProfileInt

GetProfileSection

GetProfileString

GetProp

getprotobyname

getprotobynumber

GetQueuedCompletionStatus

GetQueueStatus

GetRasterizerCaps

GetRegionData

GetResourceID

GetRgnBox

GetROP2

GetSaveFileName

GetScrollInfo  (preliminaryWindows NT)

GetScrollPos

GetScrollRange

GetSecurityDescriptorControl

GetSecurityDescriptorDacl

GetSecurityDescriptorGroup

GetSecurityDescriptorLength

GetSecurityDescriptorOwner

GetSecurityDescriptorSacl

getservbyname

getservbyport

GetService

GetServiceDisplayName

GetServiceKeyName

GetShortPathName

GetSidIdentifierAuthority

GetSidLengthRequired

GetSidSubAuthority

GetSidSubAuthorityCount

getsockname

getsockopt

GetStartupInfo

GetStdHandle

GetStockObject

GetStretchBltMode

GetStringTypeA

GetStringTypeEx

GetStringTypeW

GetSubMenu

GetSysColor

GetSysColorBrush  (preliminaryWindows 95)

GetSysModalWindow

GetSystemDefaultLangID

GetSystemDefaultLCID

GetSystemDir

GetSystemDirectory

GetSystemInfo

GetSystemMenu

GetSystemMetrics

GetSystemPaletteEntries

GetSystemPaletteUse

GetSystemPowerStatus  (preliminaryWindows 95)

GetSystemTime

GetSystemTimeAdjustment

GetTabbedTextExtent

GetTapeParameters

GetTapePosition

GetTapeStatus

GetTempDrive

GetTempFileName

GetTempPath

GetTextAlign

GetTextCharacterExtra

GetTextCharsetInfo  (preliminaryWindows 95)

GetTextColor

GetTextExtent

GetTextExtentExPoint

GetTextExtentPoint

GetTextExtentPoint32

GetTextFace

GetTextMetrics

GetThreadContext

GetThreadDesktop

GetThreadLocale

GetThreadPriority

GetThreadSelectorEntry

GetThreadTimes

GetThresholdEvent

GetThresholdStatus

GetTickCount

GetTimeFormat

GetTimeZoneInformation

GetTokenInformation

GetTopWindow

GetTypeByName

GetUpdateRect

GetUpdateRgn

GetUserDefaultLangID

GetUserDefaultLCID

GetUserName

GetUserObjectInformation  (preliminaryWindows NT)

GetUserObjectSecurity

GetVersion

GetVersionEx

GetViewportExt

GetViewportExtEx

GetViewportOrg

GetViewportOrgEx

GetVolumeInformation

GetWindow

GetWindowContextHelpId  (preliminaryWindows NT)

GetWindowDC

GetWindowExt

GetWindowExtEx

GetWindowLong

GetWindowOrg

GetWindowOrgEx

GetWindowPlacement

GetWindowRect

GetWindowRgn  (preliminaryWindows NT)

GetWindowsDir

GetWindowsDirectory

GetWindowTask

GetWindowText

GetWindowTextLength

GetWindowThreadProcessId

GetWindowWord

GetWinFlags

GetWinMetaFileBits

GetWorldTransform

GlobalAddAtom

GlobalAlloc

GlobalCompact

GlobalDeleteAtom

GlobalDiscard

GlobalDosAlloc

GlobalDosFree

GlobalFindAtom

GlobalFix

GlobalFlags

GlobalFree

GlobalGetAtomName

GlobalHandle

GlobalLock

GlobalLRUNewest

GlobalLRUOldest

GlobalMemoryStatus

GlobalNotify

GlobalPageLock

GlobalPageUnlock

GlobalReAlloc

GlobalSize

GlobalUnfix

GlobalUnlock

GlobalUnWire

GlobalWire

GrayString

H

Handler

HandlerRoutine

HeapAlloc

HeapCompact

HeapCreate

HeapDestroy

HeapFree

HeapLock

HeapReAlloc

HeapSize

HeapUnlock

HeapValidate

HeapWalk

HideCaret

HiliteMenuItem

htonl

htons

I

ImageList_Add  (preliminaryWindows NT)

ImageList_AddIcon  (preliminaryWindows NT)

ImageList_AddMasked  (preliminaryWindows NT)

ImageList_BeginDrag  (preliminaryWindows NT)

ImageList_Create  (preliminaryWindows NT)

ImageList_Destroy  (preliminaryWindows NT)

ImageList_DragEnter  (preliminaryWindows NT)

ImageList_DragLeave  (preliminaryWindows NT)

ImageList_DragMove  (preliminaryWindows NT)

ImageList_DragShowNolock  (preliminaryWindows NT)

ImageList_Draw  (preliminaryWindows NT)

ImageList_DrawEx  (preliminaryWindows NT)

ImageList_EndDrag  (preliminaryWindows NT)

ImageList_ExtractIcon  (preliminaryWindows NT)

ImageList_GetBkColor  (preliminaryWindows NT)

ImageList_GetDragImage  (preliminaryWindows NT)

ImageList_GetIcon  (preliminaryWindows NT)

ImageList_GetIconSize  (preliminaryWindows NT)

ImageList_GetImageCount  (preliminaryWindows NT)

ImageList_GetImageInfo  (preliminaryWindows NT)

ImageList_LoadBitmap  (preliminaryWindows NT)

ImageList_LoadImage  (preliminaryWindows NT)

ImageList_Merge  (preliminaryWindows NT)

ImageList_Read  (preliminaryWindows NT)

ImageList_Remove  (preliminaryWindows NT)

ImageList_Replace  (preliminaryWindows NT)

ImageList_ReplaceIcon  (preliminaryWindows NT)

ImageList_SetBkColor  (preliminaryWindows NT)

ImageList_SetDragCursorImage  (preliminaryWindows NT)

ImageList_SetIconSize  (preliminaryWindows NT)

ImageList_SetOverlayImage  (preliminaryWindows NT)

ImageList_Write  (preliminaryWindows NT)

ImmAssociateContext  (preliminaryWindows 95)

ImmConfigureIME  (preliminaryWindows 95)

ImmCreateContext  (preliminaryWindows 95)

ImmDestroyContext  (preliminaryWindows 95)

ImmEnumRegisterWord  (preliminaryWindows 95)

ImmEscape  (preliminaryWindows 95)

ImmGetCandidateList  (preliminaryWindows 95)

ImmGetCandidateListCount  (preliminaryWindows 95)

ImmGetCandidateWindow  (preliminaryWindows 95)

ImmGetCompositionFont  (preliminaryWindows 95)

ImmGetCompositionString  (preliminaryWindows 95)

ImmGetCompositionWindow  (preliminaryWindows 95)

ImmGetContext  (preliminaryWindows 95)

ImmGetConversionList  (preliminaryWindows 95)

ImmGetConversionStatus  (preliminaryWindows 95)

ImmGetDefaultIMEWnd  (preliminaryWindows 95)

ImmGetDescription  (preliminaryWindows 95)

ImmGetGuideLine  (preliminaryWindows 95)

ImmGetIMEFileName  (preliminaryWindows 95)

ImmGetOpenStatus  (preliminaryWindows 95)

ImmGetProperty  (preliminaryWindows 95)

ImmGetRegisterWordStyle  (preliminaryWindows 95)

ImmGetStatusWindowPos  (preliminaryWindows 95)

ImmGetVirtualKey  (preliminaryWindows 95)

ImmInstallIME  (preliminaryWindows 95)

ImmIsIME  (preliminaryWindows 95)

ImmIsUIMessage  (preliminaryWindows 95)

ImmNotifyIME  (preliminaryWindows 95)

ImmRegisterWord  (preliminaryWindows 95)

ImmReleaseContext  (preliminaryWindows 95)

ImmSetCandidateWindow  (preliminaryWindows 95)

ImmSetCompositionFont  (preliminaryWindows 95)

ImmSetCompositionString  (preliminaryWindows 95)

ImmSetCompositionWindow  (preliminaryWindows 95)

ImmSetConversionStatus  (preliminaryWindows 95)

ImmSetOpenStatus  (preliminaryWindows 95)

ImmSetStatusWindowPos  (preliminaryWindows 95)

ImmSimulateHotKey  (preliminaryWindows 95)

ImmUnregisterWord  (preliminaryWindows 95)

ImpersonateDdeClientWindow

ImpersonateLoggedOnUser  (preliminaryWindows NT)

ImpersonateNamedPipeClient

ImpersonateSelf

inet_addr

inet_ntoa

InflateRect

InitAtomTable

InitCommonControls  (preliminaryWindows NT)

InitializeAcl

InitializeCriticalSection

InitializeSecurityDescriptor

InitializeSid

InitiateSystemShutdown

InSendMessage

InsertMenu

InsertMenuItem  (preliminaryWindows 95)

Int32x32To64

Int64ShllMod32

Int64ShraMod32

Int64ShrlMod32

InterlockedDecrement

InterlockedExchange

InterlockedIncrement

IntersectClipRect

IntersectRect

InvalidateRect

InvalidateRgn

InvertRect

InvertRgn

IOCTL_DISK_CHECK_VERIFY

IOCTL_DISK_EJECT_MEDIA

IOCTL_DISK_FORMAT_TRACKS

IOCTL_DISK_GET_DRIVE_GEOMETRY

IOCTL_DISK_GET_DRIVE_LAYOUT

IOCTL_DISK_GET_MEDIA_TYPES

IOCTL_DISK_GET_PARTITION_INFO

IOCTL_DISK_LOAD_MEDIA

IOCTL_DISK_MEDIA_REMOVAL

IOCTL_DISK_PERFORMANCE

IOCTL_DISK_REASSIGN_BLOCKS

IOCTL_DISK_SET_DRIVE_LAYOUT

IOCTL_DISK_SET_PARTITION_INFO

IOCTL_DISK_VERIFY

IOCTL_SERIAL_LSRMST_INSERT

ioctlsocket

IsBadCodePtr

IsBadHugeReadPtr

IsBadHugeWritePtr

IsBadReadPtr

IsBadStringPtr

IsBadWritePtr

IsCharAlpha

IsCharAlphaNumeric

IsCharLower

IsCharUpper

IsChild

IsClipboardFormatAvailable

IsDBCSLeadByte

IsDBCSLeadByteEx  (preliminaryWindows NT)

IsDialogMessage

IsDlgButtonChecked

IsIconic

IsMenu

IsRectEmpty

IsTask

IsTextUnicode

IsValidAcl

IsValidCodePage

IsValidLocale

IsValidSecurityDescriptor

IsValidSid

IsWindow

IsWindowEnabled

IsWindowUnicode

IsWindowVisible

IsZoomed

J

JournalPlaybackProc

JournalRecordProc

K

keybd_event

KeyboardProc

KillTimer

L

LBItemFromPt  (preliminaryWindows NT)

LCMapString

LeaveCriticalSection

LimitEmsPages

LineDDA

LineDDAProc

LineTo

listen

LoadAccelerators

LoadBitmap

LoadCursor

LoadCursorFromFile

LoadIcon

LoadImage  (preliminaryWindows 95)

LoadImageColorMatcher  (preliminaryWindows 95)

LoadKeyboardLayout

LoadLibrary

LoadLibraryEx

LoadMenu

LoadMenuIndirect

LoadModule

LoadResource

LoadString

LocalAlloc

LocalCompact

LocalDiscard

LocalFileTimeToFileTime

LocalFlags

LocalFree

LocalHandle

LocalInit

LocalLock

LocalReAlloc

LocalShrink

LocalSize

LocalUnlock

LockFile

LockFileEx

LockResource

LockSegment

LockServiceDatabase

LockWindowUpdate

LogonUser  (preliminaryWindows NT)

LookupAccountName

LookupAccountSid

LookupIconIdFromDirectory

LookupIconIdFromDirectoryEx  (preliminaryWindows 95)

LookupPrivilegeDisplayName

LookupPrivilegeName

LookupPrivilegeValue

LPtoDP

lstrcat

lstrcmp

lstrcmpi

lstrcpy

lstrcpyn

lstrlen

LZClose

LZCopy

LZDone

LZInit

LZOpenFile

LZRead

LZSeek

LZStart

M

MakeAbsoluteSD

MakeDragList  (preliminaryWindows NT)

MakeProcInstance

MakeSelfRelativeSD

MapDialogRect

MapGenericMask

MapViewOfFile

MapViewOfFileEx

MapVirtualKey

MapVirtualKeyEx  (preliminaryWindows 95)

MapWindowPoints

MaskBlt

MenuHelp  (preliminaryWindows NT)

MenuItemFromPoint  (preliminaryWindows 95)

MessageBeep

MessageBox

MessageBoxEx

MessageBoxIndirect  (preliminaryWindows 95)

MessageProc

ModifyMenu

ModifyWorldTransform

mouse_event

MouseProc

MoveFile

MoveFileEx

MoveMemory

MoveTo

MoveToEx

MoveWindow

MsgWaitForMultipleObjects

MulDiv

MultiByteToWideChar

N

NDdeGetErrorString

NDdeGetShareSecurity

NDdeGetTrustedShare

NDdeIsValidAppTopicList

NDdeIsValidShareName

NDdeSetShareSecurity

NDdeSetTrustedShare

NDdeShareAdd

NDdeShareDel

NDdeShareEnum

NDdeShareGetInfo

NDdeShareSetInfo

NDdeTrustedShareEnum

NetAccessAdd

NetAccessCheck

NetAccessDel

NetAccessEnum

NetAccessGetInfo

NetAccessGetUserPerms

NetAccessSetInfo

NetAlertRaise

NetAlertRaiseEx

NetApiBufferAllocate

NetApiBufferFree

NetApiBufferReallocate

NetApiBufferSize

NetAuditClear

NetAuditRead

Netbios

NetConfigGet

NetConfigGetAll

NetConfigSet

NetConnectionEnum

NetErrorLogClear

NetErrorLogRead

NetFileClose

NetFileEnum

NetFileGetInfo

NetGetDCName

NetGroupAdd

NetGroupAddUser

NetGroupDel

NetGroupDelUser

NetGroupEnum

NetGroupGetInfo

NetGroupGetUsers

NetGroupSetInfo

NetGroupSetUsers

NetLocalGroupAdd

NetLocalGroupAddMember

NetLocalGroupDel

NetLocalGroupDelMember

NetLocalGroupEnum

NetLocalGroupGetInfo

NetLocalGroupGetMembers

NetLocalGroupSetInfo

NetLocalGroupSetMembers

NetMessageBufferSend

NetMessageNameAdd

NetMessageNameDel

NetMessageNameEnum

NetMessageNameGetInfo

NetRemoteTOD

NetReplExportDirAdd

NetReplExportDirDel

NetReplExportDirEnum

NetReplExportDirGetInfo

NetReplExportDirLock

NetReplExportDirSetInfo

NetReplExportDirUnlock

NetReplGetInfo

NetReplImportDirAdd

NetReplImportDirDel

NetReplImportDirEnum

NetReplImportDirGetInfo

NetReplImportDirLock

NetReplImportDirUnlock

NetReplSetInfo

NetScheduleJobAdd

NetScheduleJobDel

NetScheduleJobEnum

NetScheduleJobGetInfo

NetServerDiskEnum

NetServerEnum

NetServerGetInfo

NetServerSetInfo

NetServerTransportAdd

NetServerTransportDel

NetServerTransportEnum

NetServiceControl

NetServiceEnum

NetServiceGetInfo

NetServiceInstall

NetSessionDel

NetSessionEnum

NetSessionGetInfo

NetShareAdd

NetShareCheck

NetShareDel

NetShareEnum

NetShareGetInfo

NetShareSetInfo

NetStatisticsGet

NetUseAdd

NetUseDel

NetUseEnum

NetUseGetInfo

NetUserAdd

NetUserChangePassword  (preliminaryWindows NT)

NetUserDel

NetUserEnum

NetUserGetGroups

NetUserGetInfo

NetUserGetLocalGroups

NetUserModalsGet

NetUserModalsSet

NetUserSetGroups

NetUserSetInfo

NetWkstaGetInfo

NetWkstaSetInfo

NetWkstaTransportAdd

NetWkstaTransportDel

NetWkstaTransportEnum

NetWkstaUserEnum

NetWkstaUserGetInfo

NetWkstaUserSetInfo

NotifyBootConfigStatus

NotifyChangeEventLog

ntohl

ntohs

O

ObjectCloseAuditAlarm

ObjectOpenAuditAlarm

ObjectPrivilegeAuditAlarm

OemKeyScan

OemToAnsi

OemToAnsiBuff

OemToChar

OemToCharBuff

OffsetClipRgn

OffsetRect

OffsetRgn

OffsetViewportOrg

OffsetViewportOrgEx

OffsetWindowOrg

OffsetWindowOrgEx

OpenBackupEventLog

OpenClipboard

OpenDesktop  (preliminaryWindows NT)

OpenEvent

OpenEventLog

OpenFile

OpenFileMapping

OpenIcon

OpenInputDesktop  (preliminaryWindows NT)

OpenMutex

OpenPrinter

OpenProcess

OpenProcessToken

OpenSCManager

OpenSemaphore

OpenService

OpenSound

OpenThreadToken

OpenWindowStation  (preliminaryWindows NT)

OutputDebugString

OutputProc

P

PackDDElParam

PaintDesktop  (preliminaryWindows 95)

PaintRgn

PatBlt

PathToRegion

PeekConsoleInput

PeekMessage

PeekNamedPipe

Pie

PlayEnhMetaFile

PlayEnhMetaFileRecord

PlayMetaFile

PlayMetaFileRecord

PlgBlt

PolyBezier

PolyBezierTo

PolyDraw

Polygon

Polyline

PolylineTo

PolyPolygon

PolyPolyline

PolyTextOut

PostAppMessage

PostMessage

PostQueuedCompletionStatus  (preliminaryWindows NT)

PostQuitMessage

PostThreadMessage

PrepareTape

PrintDlg

PrinterMessageBox

PrinterProperties

PrivilegeCheck

PrivilegedServiceAuditAlarm

ProfClear

ProfFinish

ProfFlush

ProfInsChk

ProfSampRate

ProfSetup

ProfStart

ProfStop

PropEnumProc

PropEnumProcEx

PropertySheet  (preliminaryWindows NT)

PropSheetPageProc  (preliminaryWindows NT)

PropSheetProc  (preliminaryWindows NT)

PtInRect

PtInRegion

PtVisible

PulseEvent

PurgeComm

Q

QueryDosDevice

QueryPerformanceCounter

QueryPerformanceFrequency

QueryServiceConfig

QueryServiceLockStatus

QueryServiceObjectSecurity

QueryServiceStatus

R

RaiseException

RasCreatePhonebookEntry

RasDial

RasDialFunc

RasDialFunc1

RasEditPhonebookEntry

RasEnumConnections

RasEnumEntries

RasGetConnectStatus

RasGetEntryDialParams

RasGetErrorString

RasGetProjectionInfo

RasHangUp

RasSetEntryDialParams

ReadConsole

ReadConsoleInput

ReadConsoleOutput

ReadConsoleOutputAttribute

ReadConsoleOutputCharacter

ReadEventLog

ReadFile

ReadFileEx

ReadPrinter

ReadProcessMemory

RealizePalette

Rectangle

RectInRegion

RectVisible

recv

recvfrom

RedrawWindow

RegCloseKey

RegConnectRegistry

RegCreateKey

RegCreateKeyEx

RegDeleteKey

RegDeleteValue

RegEnumKey

RegEnumKeyEx

RegEnumValue

RegFlushKey

RegGetKeySecurity

RegisterClass

RegisterClassEx  (preliminaryWindows 95)

RegisterClipboardFormat

RegisterDialogClasses

RegisterEventSource

RegisterHotKey

RegisterServiceCtrlHandler

RegisterWindowMessage

RegLoadKey

RegNotifyChangeKeyValue

RegOpenKey

RegOpenKeyEx

RegQueryInfoKey

RegQueryMultipleValues

RegQueryValue

RegQueryValueEx

RegReplaceKey

RegRestoreKey

RegSaveKey

RegSetKeySecurity

RegSetValue

RegSetValueEx

RegUnLoadKey

ReleaseCapture

ReleaseDC

ReleaseMutex

ReleaseSemaphore

RemoveDirectory

RemoveFontResource

RemoveMenu

RemoveProp

ReplaceText

ReplyMessage

ReportEvent

ResetDC

ResetDisplay

ResetEvent

ResetPrinter

ResizePalette

RestoreDC

ResumeThread

ReuseDDElParam

RevertToSelf

RoundRect

S

SaveDC

ScaleViewportExt

ScaleViewportExtEx

ScaleWindowExt

ScaleWindowExtEx

ScheduleJob

ScreenSaverConfigureDialog

ScreenSaverProc

ScreenToClient

ScrollConsoleScreenBuffer

ScrollDC

ScrollWindow

ScrollWindowEx

SearchPath

select

SelectClipPath

SelectClipRgn

SelectObject

SelectPalette

send

SendAsyncProc

SendDlgItemMessage

SendMessage

SendMessageCallback

SendMessageTimeout

SendNotifyMessage

sendto

ServiceMain

SetAbortProc

SetAclInformation

SetActiveWindow

SetArcDirection

SetBitmapBits

SetBitmapDimension

SetBitmapDimensionEx

SetBkColor

SetBkMode

SetBoundsRect

SetBrushOrg

SetBrushOrgEx

SetCapture

SetCaretBlinkTime

SetCaretPos

SetClassLong

SetClassWord

SetClipboardData

SetClipboardViewer

SetColorAdjustment

SetColorSpace  (preliminaryWindows 95)

SetCommBreak

SetCommConfig  (preliminaryWindows 95)

SetCommMask

SetCommState

SetCommTimeouts

SetComputerName

SetConsoleActiveScreenBuffer

SetConsoleCP

SetConsoleCtrlHandler

SetConsoleCursorInfo

SetConsoleCursorPosition

SetConsoleMode

SetConsoleOutputCP

SetConsoleScreenBufferSize

SetConsoleTextAttribute

SetConsoleTitle

SetConsoleWindowInfo

SetCurrentDirectory

SetCursor

SetCursorPos

SetDebugErrorLevel

SetDefaultCommConfig  (preliminaryWindows 95)

SetDeviceGammaRamp  (preliminaryWindows 95)

SetDIBColorTable

SetDIBits

SetDIBitsToDevice

SetDlgItemInt

SetDlgItemText

SetDoubleClickTime

SetEndOfFile

SetEnhMetaFileBits

SetEnvironmentVariable

SetErrorMode

SetEvent

SetFileApisToANSI

SetFileApisToOEM

SetFileAttributes

SetFilePointer

SetFileSecurity

SetFileTime

SetFocus

SetForegroundWindow

SetForm

SetGraphicsMode

SetHandleCount

SetHandleInformation  (preliminaryWindows NT)

SetICMMode  (preliminaryWindows 95)

SetICMProfile  (preliminaryWindows 95)

SetJob

SetKernelObjectSecurity

SetKeyboardState

SetLastError

SetLastErrorEx

SetLocaleInfo

SetLocalTime

SetMailslotInfo

SetMapMode

SetMapperFlags

SetMenu

SetMenuContextHelpId  (preliminaryWindows NT)

SetMenuDefaultItem  (preliminaryWindows 95)

SetMenuItemBitmaps

SetMenuItemInfo  (preliminaryWindows 95)

SetMessageExtraInfo  (preliminaryWindows 95)

SetMessageQueue

SetMetaFileBits

SetMetaFileBitsEx

SetMetaRgn

SetMiterLimit

SetNamedPipeHandleState

SetPaletteEntries

SetParent

SetPixel

SetPixelV

SetPolyFillMode

SetPrinter

SetPrinterData

SetPriorityClass

SetPrivateObjectSecurity

SetProcessShutdownParameters

SetProcessWindowStation  (preliminaryWindows NT)

SetProcessWorkingSetSize

SetProp

SetRect

SetRectEmpty

SetRectRgn

SetResourceHandler

SetROP2

SetScrollInfo  (preliminaryWindows NT)

SetScrollPos

SetScrollRange

SetSecurityDescriptorDacl

SetSecurityDescriptorGroup

SetSecurityDescriptorOwner

SetSecurityDescriptorSacl

SetService

SetServiceBits

SetServiceObjectSecurity

SetServiceStatus

setsockopt

SetSoundNoise

SetStdHandle

SetStretchBltMode

SetSwapAreaSize

SetSysColors

SetSysModalWindow

SetSystemCursor

SetSystemPaletteUse

SetSystemPowerState  (preliminaryWindows 95)

SetSystemTime

SetSystemTimeAdjustment

SetTapeParameters

SetTapePosition

SetTextAlign

SetTextCharacterExtra

SetTextColor

SetTextJustification

SetThreadAffinityMask

SetThreadContext

SetThreadDesktop  (preliminaryWindows NT)

SetThreadLocale

SetThreadPriority

SetThreadToken

SetTimer

SetTimeZoneInformation

SetTokenInformation

SetUnhandledExceptionFilter

SetupComm

SetUserObjectInformation  (preliminaryWindows NT)

SetUserObjectSecurity

SetViewportExt

SetViewportExtEx

SetViewportOrg

SetViewportOrgEx

SetVoiceAccent

SetVoiceEnvelope

SetVoiceNote

SetVoiceQueueSize

SetVoiceSound

SetVoiceThreshold

SetVolumeLabel

SetWindowContextHelpId  (preliminaryWindows NT)

SetWindowExt

SetWindowExtEx

SetWindowLong

SetWindowOrg

SetWindowOrgEx

SetWindowPlacement

SetWindowPos

SetWindowRgn  (preliminaryWindows NT)

SetWindowsHook

SetWindowsHookEx

SetWindowText

SetWindowWord

SetWinMetaFileBits

SetWorldTransform

SHAddToRecentDocs

SHAppBarMessage

SHBrowseForFolder

SHChangeNotify

ShellAbout

ShellExecute

ShellProc

SHFileOperation

SHFreeNameMappings

SHGetDesktopFolder

SHGetFileInfo

SHGetInstanceExplorer

SHGetNameMappingCount

SHGetNameMappingPtr

SHGetPathFromIDList

SHGetSpecialFolderLocation

SHLoadInProc

ShowCaret

ShowCursor

ShowHideMenuCtl  (preliminaryWindows NT)

ShowOwnedPopups

ShowScrollBar

ShowWindow

ShowWindowAsync  (preliminaryWindows 95)

shutdown

SizeofResource

Sleep

SleepEx

socket

SoundSentryProc  (preliminaryWindows NT)

StartDoc

StartDocPrinter

StartPage

StartPagePrinter

StartService

StartServiceCtrlDispatcher

StartSound

StopSound

StretchBlt

StretchDIBits

StrokeAndFillPath

StrokePath

SubtractRect

SuspendThread

SwapMouseButton

SwitchDesktop  (preliminaryWindows NT)

SwitchStackBack

SwitchStackTo

SyncAllVoices

SysMsgProc

SystemParametersInfo

SystemTimeToFileTime

SystemTimeToTzSpecificLocalTime

T

TabbedTextOut

TerminateProcess

TerminateThread

TextOut

Throw

TileWindows  (preliminaryWindows 95)

TimerProc

TlsAlloc

TlsFree

TlsGetValue

TlsSetValue

ToAscii

ToAsciiEx  (preliminaryWindows 95)

ToUnicode

TrackPopupMenu

TrackPopupMenuEx  (preliminaryWindows 95)

TransactNamedPipe

TranslateAccelerator

TranslateCharsetInfo  (preliminaryWindows 95)

TranslateMDISysAccel

TranslateMessage

TransmitCommChar

TransmitFile  (preliminaryWindows NT)

U

UInt32x32To64

UndeleteFile

UnhandledExceptionFilter

UnhookWindowsHook

UnhookWindowsHookEx

UnionRect

UnloadKeyboardLayout

UnlockFile

UnlockFileEx

UnlockResource

UnlockSegment

UnlockServiceDatabase

UnmapViewOfFile

UnpackDDElParam

UnrealizeObject

UnregisterClass

UnregisterHotKey

UpdateColors

UpdateResource

UpdateWindow

V

ValidateRect

ValidateRgn

VerFindFile

VerInstallFile

VerLanguageName

VerQueryValue

VirtualAlloc

VirtualFree

VirtualLock

VirtualProtect

VirtualProtectEx

VirtualQuery

VirtualQueryEx

VirtualUnlock

VkKeyScan

VkKeyScanEx  (preliminaryWindows 95)

W

WaitCommEvent

WaitForDebugEvent

WaitForInputIdle

WaitForMultipleObjects

WaitForMultipleObjectsEx

WaitForPrinterChange

WaitForSingleObject

WaitForSingleObjectEx

WaitMessage

WaitNamedPipe

WaitSoundState

WideCharToMultiByte

WidenPath

WindowFromDC

WindowFromPoint

WindowProc

WinExec

WinHelp

WNetAddConnection2

WNetAddConnection3

WNetCancelConnection

WNetCancelConnection2

WNetCloseEnum

WNetConnectionDialog

WNetDisconnectDialog

WNetEnumResource

WNetGetConnection

WNetGetLastError

WNetGetResourceInformation

WNetGetResourceParent

WNetGetUniversalName

WNetGetUser

WNetOpenEnum

WriteConsole

WriteConsoleInput

WriteConsoleOutput

WriteConsoleOutputAttribute

WriteConsoleOutputCharacter

WriteFile

WriteFileEx

WritePrinter

WritePrivateProfileSection

WritePrivateProfileString

WritePrivateProfileStruct  (preliminaryWindows NT)

WriteProcessMemory

WriteProfileSection

WriteProfileString

WriteTapemark

WSAAsyncGetHostByAddr

WSAAsyncGetHostByName

WSAAsyncGetProtoByName

WSAAsyncGetProtoByNumber

WSAAsyncGetServByName

WSAAsyncGetServByPort

WSAAsyncSelect

WSACancelAsyncRequest

WSACancelBlockingCall

WSACleanup

WSAGetLastError

WSAIsBlocking

WSASetBlockingHook

WSASetLastError

WSAStartup

WSAUnhookBlockingHook

wsprintf

wvsprintf

X

Y

Yield

Z

ZeroMemory


Win32 API Help Contents: Messages
Messages

A

ABM_ACTIVATE

ABM_GETAUTOHIDEBAR

ABM_GETSTATE

ABM_GETTASKBARPOS

ABM_NEW

ABM_QUERYPOS

ABM_REMOVE

ABM_SETAUTOHIDEBAR

ABM_SETPOS

ABM_WINDOWPOSCHANGED

ABN_FULLSCREENAPP

ABN_POSCHANGED

ABN_STATECHANGE

ABN_WINDOWARRANGE

ACM_OPEN  (preliminaryWindows NT)

ACM_PLAY  (preliminaryWindows NT)

ACM_STOP  (preliminaryWindows NT)

ACN_START  (preliminaryWindows NT)

ACN_STOP  (preliminaryWindows NT)

B

BM_CLICK

BM_GETCHECK

BM_GETIMAGE  (preliminaryWindows 95)

BM_GETSTATE

BM_SETCHECK

BM_SETIMAGE  (preliminaryWindows 95)

BM_SETSTATE

BM_SETSTYLE

BN_CLICKED

BN_DBLCLK  (preliminaryWindows 95)

BN_DISABLE

BN_DOUBLECLICKED

BN_HILITE

BN_KILLFOCUS  (preliminaryWindows 95)

BN_PAINT

BN_PUSHED  (preliminaryWindows 95)

BN_SETFOCUS  (preliminaryWindows 95)

BN_UNHILITE

BN_UNPUSHED  (preliminaryWindows 95)

C

CBN_CLOSEUP

CBN_DBLCLK

CBN_DROPDOWN

CBN_EDITCHANGE

CBN_EDITUPDATE

CBN_ERRSPACE

CBN_KILLFOCUS

CBN_SELCHANGE

CBN_SELENDCANCEL

CBN_SELENDOK

CBN_SETFOCUS

CB_ADDSTRING

CB_DELETESTRING

CB_DIR

CB_FINDSTRING

CB_FINDSTRINGEXACT

CB_GETCOUNT

CB_GETCURSEL

CB_GETDROPPEDCONTROLRECT

CB_GETDROPPEDSTATE

CB_GETDROPPEDWIDTH  (preliminaryWindows 95)

CB_GETEDITSEL

CB_GETEXTENDEDUI

CB_GETHORIZONTALEXTENT  (preliminaryWindows 95)

CB_GETITEMDATA

CB_GETITEMHEIGHT

CB_GETLBTEXT

CB_GETLBTEXTLEN

CB_GETLOCALE

CB_GETTOPINDEX  (preliminaryWindows 95)

CB_INITSTORAGE  (preliminaryWindows 95)

CB_INSERTSTRING

CB_LIMITTEXT

CB_RESETCONTENT

CB_SELECTSTRING

CB_SETCURSEL

CB_SETDROPPEDWIDTH  (preliminaryWindows 95)

CB_SETEDITSEL

CB_SETEXTENDEDUI

CB_SETHORIZONTALEXTENT  (preliminaryWindows 95)

CB_SETITEMDATA

CB_SETITEMHEIGHT

CB_SETLOCALE

CB_SETTOPINDEX  (preliminaryWindows 95)

CB_SHOWDROPDOWN

CPL_DBLCLK

CPL_EXIT

CPL_GETCOUNT

CPL_INIT

CPL_INQUIRE

CPL_NEWINQUIRE

CPL_SELECT

CPL_STOP

D

DBT_CONFIGCHANGED  (preliminaryWindows 95)

DBT_DEVICEARRIVAL  (preliminaryWindows 95)

DBT_DEVICEQUERYREMOVE  (preliminaryWindows 95)

DBT_DEVICEQUERYREMOVEFAILED  (preliminaryWindows 95)

DBT_DEVICEREMOVECOMPLETE  (preliminaryWindows 95)

DBT_DEVICEREMOVEPENDING  (preliminaryWindows 95)

DBT_DEVICETYPESPECIFIC  (preliminaryWindows 95)

DBT_DEVNODES_CHANGED

DBT_USERDEFINED

DL_BEGINDRAG  (preliminaryWindows NT)

DL_CANCELDRAG  (preliminaryWindows NT)

DL_DRAGGING  (preliminaryWindows NT)

DL_DROPPED  (preliminaryWindows NT)

DM_GETDEFID

DM_REPOSITION  (preliminaryWindows 95)

DM_SETDEFID

E

EM_CANPASTE  (preliminaryWindows NT)

EM_CANUNDO

EM_CHARFROMPOS  (preliminaryWindows 95)

EM_DISPLAYBAND  (preliminaryWindows NT)

EM_EMPTYUNDOBUFFER

EM_EXGETSEL  (preliminaryWindows NT)

EM_EXLIMITTEXT  (preliminaryWindows NT)

EM_EXLINEFROMCHAR  (preliminaryWindows NT)

EM_EXSETSEL  (preliminaryWindows NT)

EM_FINDTEXT  (preliminaryWindows NT)

EM_FINDWORDBREAK  (preliminaryWindows NT)

EM_FMTLINES

EM_FORMATRANGE  (preliminaryWindows NT)

EM_GETCHARFORMAT  (preliminaryWindows NT)

EM_GETEVENTMASK  (preliminaryWindows NT)

EM_GETFIRSTVISIBLELINE

EM_GETHANDLE

EM_GETLIMITTEXT  (preliminaryWindows 95)

EM_GETLINE

EM_GETLINECOUNT

EM_GETMARGINS  (preliminaryWindows 95)

EM_GETMODIFY

EM_GETOLEINTERFACE  (preliminaryWindows NT)

EM_GETPARAFORMAT  (preliminaryWindows NT)

EM_GETPASSWORDCHAR

EM_GETRECT

EM_GETSEL

EM_GETSELTEXT  (preliminaryWindows NT)

EM_GETTEXTRANGE  (preliminaryWindows NT)

EM_GETTHUMB  (preliminaryWindows NT)

EM_GETWORDBREAKPROC

EM_HIDESELECTION  (preliminaryWindows NT)

EM_LIMITTEXT

EM_LINEFROMCHAR

EM_LINEINDEX

EM_LINELENGTH

EM_LINESCROLL

EM_PASTESPECIAL  (preliminaryWindows NT)

EM_POSFROMCHAR  (preliminaryWindows 95)

EM_REPLACESEL

EM_REQUESTRESIZE  (preliminaryWindows NT)

EM_SCROLL

EM_SCROLLCARET

EM_SELECTIONTYPE  (preliminaryWindows NT)

EM_SETBKGNDCOLOR  (preliminaryWindows NT)

EM_SETCHARFORMAT  (preliminaryWindows NT)

EM_SETEVENTMASK  (preliminaryWindows NT)

EM_SETHANDLE

EM_SETLIMITTEXT  (preliminaryWindows 95)

EM_SETMARGINS  (preliminaryWindows 95)

EM_SETMODIFY

EM_SETOLEINTERFACE  (preliminaryWindows NT)

EM_SETPARAFORMAT  (preliminaryWindows NT)

EM_SETPASSWORDCHAR

EM_SETREADONLY

EM_SETRECT

EM_SETRECTNP

EM_SETSEL

EM_SETTABSTOPS

EM_SETTARGETDEVICE  (preliminaryWindows NT)

EM_SETWORDBREAK

EM_SETWORDBREAKPROC

EM_STREAMIN  (preliminaryWindows NT)

EM_STREAMOUT  (preliminaryWindows NT)

EM_UNDO

EN_CHANGE

EN_DROPFILES  (preliminaryWindows NT)

EN_ERRSPACE

EN_HSCROLL

EN_KILLFOCUS

EN_MAXTEXT

EN_MSGFILTER  (preliminaryWindows NT)

EN_PROTECTED  (preliminaryWindows NT)

EN_REQUESTRESIZE  (preliminaryWindows NT)

EN_SELCHANGE  (preliminaryWindows NT)

EN_SETFOCUS

EN_UPDATE

EN_VSCROLL

F

FMEVENT_HELPMENUITEM

FMEVENT_HELPSTRING

FMEVENT_INITMENU

FMEVENT_LOAD

FMEVENT_SELCHANGE

FMEVENT_TOOLBARLOAD

FMEVENT_UNLOAD

FMEVENT_USER_REFRESH

FM_GETDRIVEINFO

FM_GETFILESEL

FM_GETFILESELLFN

FM_GETFOCUS

FM_GETSELCOUNT

FM_GETSELCOUNTLFN

FM_REFRESH_WINDOWS

FM_RELOAD_EXTENSIONS

G

H

HDM_DELETEITEM  (preliminaryWindows NT)

HDM_GETITEM  (preliminaryWindows NT)

HDM_GETITEMCOUNT  (preliminaryWindows NT)

HDM_HITTEST  (preliminaryWindows NT)

HDM_INSERTITEM  (preliminaryWindows NT)

HDM_LAYOUT  (preliminaryWindows NT)

HDM_SETITEM  (preliminaryWindows NT)

HDN_BEGINTRACK  (preliminaryWindows NT)

HDN_DIVIDERDBLCLICK  (preliminaryWindows NT)

HDN_ENDTRACK  (preliminaryWindows NT)

HDN_ITEMCHANGED  (preliminaryWindows NT)

HDN_ITEMCHANGING  (preliminaryWindows NT)

HDN_ITEMCLICK  (preliminaryWindows NT)

HDN_ITEMDBLCLICK  (preliminaryWindows NT)

HDN_TRACK  (preliminaryWindows NT)

HKM_GETHOTKEY  (preliminaryWindows NT)

HKM_SETHOTKEY  (preliminaryWindows NT)

HKM_SETRULES  (preliminaryWindows NT)

I

IMC_CLOSESTATUSWINDOW

IMC_GETCANDIDATEPOS  (preliminaryWindows 95)

IMC_GETCOMPOSITIONFONT  (preliminaryWindows 95)

IMC_GETCOMPOSITIONWINDOW  (preliminaryWindows 95)

IMC_GETCONVERSIONMODE  (preliminaryWindows 95)

IMC_GETOPENSTATUS  (preliminaryWindows 95)

IMC_GETSENTENCEMODE  (preliminaryWindows 95)

IMC_GETSTATUSWINDOWPOS  (preliminaryWindows 95)

IMC_OPENSTATUSWINDOW

IMC_SETCANDIDATEPOS  (preliminaryWindows 95)

IMC_SETCOMPOSITIONFONT  (preliminaryWindows 95)

IMC_SETCOMPOSITIONWINDOW  (preliminaryWindows 95)

IMC_SETCONVERSIONMODE  (preliminaryWindows 95)

IMC_SETOPENSTATUS  (preliminaryWindows 95)

IMC_SETSENTENCEMODE  (preliminaryWindows 95)

IMC_SETSTATUSWINDOWPOS  (preliminaryWindows 95)

IMN_CHANGECANDIDATE  (preliminaryWindows 95)

IMN_CLOSECANDIDATE  (preliminaryWindows 95)

IMN_CLOSESTATUSWINDOW(preliminaryWindows 95)

IMN_GUIDELINE(preliminaryWindows 95)

IMN_OPENCANDIDATE  (preliminaryWindows 95)

IMN_OPENSTATUSWINDOW(preliminaryWindows 95)

IMN_SETCANDIDATEPOS  (preliminaryWindows 95)

IMN_SETCOMPOSITIONFONT(preliminaryWindows 95)

IMN_SETCOMPOSITIONWINDOW(preliminaryWindows 95)

IMN_SETCONVERSIONMODE(preliminaryWindows 95)

IMN_SETOPENSTATUS(preliminaryWindows 95)

IMN_SETSENTENCEMODE(preliminaryWindows 95)

IMN_SETSTATUSWINDOWPOS(preliminaryWindows 95)

J

K

L

LBN_DBLCLK

LBN_ERRSPACE

LBN_KILLFOCUS

LBN_SELCANCEL

LBN_SELCHANGE

LBN_SETFOCUS

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_INITSTORAGE  (preliminaryWindows 95)

LB_INSERTSTRING

LB_ITEMFROMPOINT  (preliminaryWindows 95)

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

LVM_ARRANGE  (preliminaryWindows NT)

LVM_CREATEDRAGIMAGE  (preliminaryWindows NT)

LVM_DELETEALLITEMS  (preliminaryWindows NT)

LVM_DELETECOLUMN  (preliminaryWindows NT)

LVM_DELETEITEM  (preliminaryWindows NT)

LVM_EDITLABEL  (preliminaryWindows NT)

LVM_ENSUREVISIBLE  (preliminaryWindows NT)

LVM_FINDITEM  (preliminaryWindows NT)

LVM_GETBKCOLOR  (preliminaryWindows NT)

LVM_GETCALLBACKMASK  (preliminaryWindows NT)

LVM_GETCOLUMN  (preliminaryWindows NT)

LVM_GETCOLUMNWIDTH  (preliminaryWindows NT)

LVM_GETCOUNTPERPAGE  (preliminaryWindows NT)

LVM_GETEDITCONTROL  (preliminaryWindows NT)

LVM_GETIMAGELIST  (preliminaryWindows NT)

LVM_GETISEARCHSTRING

LVM_GETITEM  (preliminaryWindows NT)

LVM_GETITEMCOUNT  (preliminaryWindows NT)

LVM_GETITEMPOSITION  (preliminaryWindows NT)

LVM_GETITEMRECT  (preliminaryWindows NT)

LVM_GETITEMSPACING  (preliminaryWindows NT)

LVM_GETITEMSTATE  (preliminaryWindows NT)

LVM_GETITEMTEXT  (preliminaryWindows NT)

LVM_GETNEXTITEM  (preliminaryWindows NT)

LVM_GETORIGIN  (preliminaryWindows NT)

LVM_GETSELECTEDCOUNT  (preliminaryWindows NT)

LVM_GETSTRINGWIDTH  (preliminaryWindows NT)

LVM_GETTEXTBKCOLOR  (preliminaryWindows NT)

LVM_GETTEXTCOLOR  (preliminaryWindows NT)

LVM_GETTOPINDEX  (preliminaryWindows NT)

LVM_GETVIEWRECT  (preliminaryWindows NT)

LVM_HITTEST  (preliminaryWindows NT)

LVM_INSERTCOLUMN  (preliminaryWindows NT)

LVM_INSERTITEM  (preliminaryWindows NT)

LVM_REDRAWITEMS  (preliminaryWindows NT)

LVM_SCROLL  (preliminaryWindows NT)

LVM_SETBKCOLOR  (preliminaryWindows NT)

LVM_SETCALLBACKMASK  (preliminaryWindows NT)

LVM_SETCOLUMN  (preliminaryWindows NT)

LVM_SETCOLUMNWIDTH  (preliminaryWindows NT)

LVM_SETIMAGELIST  (preliminaryWindows NT)

LVM_SETITEM  (preliminaryWindows NT)

LVM_SETITEMCOUNT  (preliminaryWindows NT)

LVM_SETITEMPOSITION  (preliminaryWindows NT)

LVM_SETITEMPOSITION32  (preliminaryWindows NT)

LVM_SETITEMSTATE  (preliminaryWindows NT)

LVM_SETITEMTEXT  (preliminaryWindows NT)

LVM_SETTEXTBKCOLOR  (preliminaryWindows NT)

LVM_SETTEXTCOLOR  (preliminaryWindows NT)

LVM_SORTITEMS  (preliminaryWindows NT)

LVM_UPDATE  (preliminaryWindows NT)

LVN_BEGINDRAG  (preliminaryWindows NT)

LVN_BEGINLABELEDIT  (preliminaryWindows NT)

LVN_BEGINRDRAG  (preliminaryWindows NT)

LVN_COLUMNCLICK  (preliminaryWindows NT)

LVN_DELETEALLITEMS  (preliminaryWindows NT)

LVN_DELETEITEM  (preliminaryWindows NT)

LVN_ENDLABELEDIT  (preliminaryWindows NT)

LVN_GETDISPINFO  (preliminaryWindows NT)

LVN_INSERTITEM  (preliminaryWindows NT)

LVN_ITEMCHANGED  (preliminaryWindows NT)

LVN_ITEMCHANGING  (preliminaryWindows NT)

LVN_KEYDOWN  (preliminaryWindows NT)

LVN_PEN  (preliminaryWindows NT)

LVN_SETDISPINFO  (preliminaryWindows NT)

M

N

NM_CLICK  (preliminaryWindows NT)

NM_DBLCLK  (preliminaryWindows NT)

NM_KILLFOCUS  (preliminaryWindows NT)

NM_OUTOFMEMORY  (preliminaryWindows NT)

NM_RCLICK  (preliminaryWindows NT)

NM_RDBLCLK  (preliminaryWindows NT)

NM_RETURN  (preliminaryWindows NT)

NM_SETFOCUS  (preliminaryWindows NT)

O

P

PBM_DELTAPOS  (preliminaryWindows 95)

PBM_SETPOS  (preliminaryWindows 95)

PBM_SETRANGE  (preliminaryWindows 95)

PBM_SETSTEP  (preliminaryWindows 95)

PBM_STEPIT  (preliminaryWindows 95)

PB_APMPOWERSTATUSCHANGED  (preliminaryWindows 95)

PB_APMQUERYSTANDBY  (preliminaryWindows 95)

PB_APMQUERYSTANDBYFAILED  (preliminaryWindows 95)

PB_APMQUERYSUSPEND  (preliminaryWindows 95)

PB_APMQUERYSUSPENDFAILED  (preliminaryWindows 95)

PB_APMRESUMECRITICAL  (preliminaryWindows 95)

PB_APMRESUMESTANDBY  (preliminaryWindows 95)

PB_APMRESUMESUSPEND  (preliminaryWindows 95)

PB_APMSTANDBY  (preliminaryWindows 95)

PB_APMSUSPEND  (preliminaryWindows 95)

PSM_ADDPAGE  (preliminaryWindows NT)

PSM_APPLY  (preliminaryWindows NT)

PSM_CANCELTOCLOSE  (preliminaryWindows NT)

PSM_CHANGED  (preliminaryWindows NT)

PSM_GETTABCONTROL  (preliminaryWindows NT)

PSM_PRESSBUTTON  (preliminaryWindows NT)

PSM_QUERYSIBLINGS  (preliminaryWindows NT)

PSM_REBOOTSYSTEM  (preliminaryWindows NT)

PSM_REMOVEPAGE  (preliminaryWindows NT)

PSM_RESTARTWINDOWS  (preliminaryWindows NT)

PSM_SETCURSEL  (preliminaryWindows NT)

PSM_SETCURSELID  (preliminaryWindows NT)

PSM_SETFINISHTEXT  (preliminaryWindows NT)

PSM_SETTITLE  (preliminaryWindows NT)

PSM_SETWIZBUTTONS  (preliminaryWindows NT)

PSM_UNCHANGED  (preliminaryWindows NT)

PSN_APPLY  (preliminaryWindows NT)

PSN_HELP  (preliminaryWindows NT)

PSN_KILLACTIVE  (preliminaryWindows NT)

PSN_QUERYCANCEL  (preliminaryWindows NT)

PSN_RESET  (preliminaryWindows NT)

PSN_SETACTIVE  (preliminaryWindows NT)

PSN_WIZBACK  (preliminaryWindows NT)

PSN_WIZFINISH  (preliminaryWindows NT)

PSN_WIZNEXT  (preliminaryWindows NT)

Q

R

S

SBM_ENABLE_ARROWS

SBM_GETPOS

SBM_GETRANGE

SBM_GETSCROLLINFO  (preliminaryWindows NT)

SBM_SETPOS

SBM_SETRANGE

SBM_SETRANGEREDRAW

SBM_SETSCROLLINFO  (preliminaryWindows NT)

SB_GETBORDERS  (preliminaryWindows NT)

SB_GETPARTS  (preliminaryWindows NT)

SB_GETRECT  (preliminaryWindows NT)

SB_GETTEXT  (preliminaryWindows NT)

SB_GETTEXTLENGTH  (preliminaryWindows NT)

SB_SETMINHEIGHT  (preliminaryWindows NT)

SB_SETPARTS  (preliminaryWindows NT)

SB_SETTEXT  (preliminaryWindows NT)

SB_SIMPLE  (preliminaryWindows NT)

STM_GETICON

STM_GETIMAGE  (preliminaryWindows NT)

STM_SETICON

STM_SETIMAGE  (preliminaryWindows NT)

STN_CLICKED  (preliminaryWindows 95)

STN_DBLCLK  (preliminaryWindows 95)

STN_DISABLE  (preliminaryWindows 95)

STN_ENABLE  (preliminaryWindows 95)

T

TBM_CLEARSEL  (preliminaryWindows NT)

TBM_CLEARTICS  (preliminaryWindows NT)

TBM_GETCHANNELRECT  (preliminaryWindows NT)

TBM_GETLINESIZE  (preliminaryWindows NT)

TBM_GETNUMTICS  (preliminaryWindows NT)

TBM_GETPAGESIZE  (preliminaryWindows NT)

TBM_GETPOS  (preliminaryWindows NT)

TBM_GETPTICS  (preliminaryWindows NT)

TBM_GETRANGEMAX  (preliminaryWindows NT)

TBM_GETRANGEMIN  (preliminaryWindows NT)

TBM_GETSELEND  (preliminaryWindows NT)

TBM_GETSELSTART  (preliminaryWindows NT)

TBM_GETTHUMBLENGTH  (preliminaryWindows NT)

TBM_GETTHUMBRECT  (preliminaryWindows NT)

TBM_GETTIC  (preliminaryWindows NT)

TBM_GETTICPOS  (preliminaryWindows NT)

TBM_SETLINESIZE  (preliminaryWindows NT)

TBM_SETPAGESIZE  (preliminaryWindows NT)

TBM_SETPOS  (preliminaryWindows NT)

TBM_SETRANGE  (preliminaryWindows NT)

TBM_SETRANGEMAX  (preliminaryWindows NT)

TBM_SETRANGEMIN  (preliminaryWindows NT)

TBM_SETSEL  (preliminaryWindows NT)

TBM_SETSELEND  (preliminaryWindows NT)

TBM_SETSELSTART  (preliminaryWindows NT)

TBM_SETTHUMBLENGTH  (preliminaryWindows NT)

TBM_SETTIC  (preliminaryWindows NT)

TBM_SETTICFREQ  (preliminaryWindows NT)

TBN_BEGINADJUST  (preliminaryWindows NT)

TBN_BEGINDRAG  (preliminaryWindows NT)

TBN_CUSTHELP  (preliminaryWindows NT)

TBN_ENDADJUST  (preliminaryWindows NT)

TBN_ENDDRAG  (preliminaryWindows NT)

TBN_GETBUTTONINFO  (preliminaryWindows NT)

TBN_QUERYDELETE  (preliminaryWindows NT)

TBN_QUERYINSERT  (preliminaryWindows NT)

TBN_RESET  (preliminaryWindows NT)

TBN_TOOLBARCHANGE  (preliminaryWindows NT)

TB_ADDBITMAP  (preliminaryWindows NT)

TB_ADDBUTTONS  (preliminaryWindows NT)

TB_ADDSTRING  (preliminaryWindows NT)

TB_AUTOSIZE  (preliminaryWindows NT)

TB_BUTTONCOUNT  (preliminaryWindows NT)

TB_BUTTONSTRUCTSIZE  (preliminaryWindows NT)

TB_CHANGEBITMAP  (preliminaryWindows NT)

TB_CHECKBUTTON  (preliminaryWindows NT)

TB_COMMANDTOINDEX  (preliminaryWindows NT)

TB_CUSTOMIZE  (preliminaryWindows NT)

TB_DELETEBUTTON  (preliminaryWindows NT)

TB_ENABLEBUTTON  (preliminaryWindows NT)

TB_GETBITMAP  (preliminaryWindows NT)

TB_GETBITMAPFLAGS  (preliminaryWindows NT)

TB_GETBUTTON  (preliminaryWindows NT)

TB_GETBUTTONTEXT  (preliminaryWindows NT)

TB_GETITEMRECT  (preliminaryWindows NT)

TB_GETROWS  (preliminaryWindows NT)

TB_GETSTATE  (preliminaryWindows NT)

TB_GETTOOLTIPS  (preliminaryWindows NT)

TB_HIDEBUTTON  (preliminaryWindows NT)

TB_INDETERMINATE  (preliminaryWindows NT)

TB_INSERTBUTTON  (preliminaryWindows NT)

TB_ISBUTTONCHECKED  (preliminaryWindows NT)

TB_ISBUTTONENABLED  (preliminaryWindows NT)

TB_ISBUTTONHIDDEN  (preliminaryWindows NT)

TB_ISBUTTONINDETERMINATE  (preliminaryWindows NT)

TB_ISBUTTONPRESSED  (preliminaryWindows NT)

TB_PRESSBUTTON  (preliminaryWindows NT)

TB_SAVERESTORE  (preliminaryWindows NT)

TB_SETBITMAPSIZE  (preliminaryWindows NT)

TB_SETBUTTONSIZE  (preliminaryWindows NT)

TB_SETCMDID  (preliminaryWindows NT)

TB_SETPARENT  (preliminaryWindows NT)

TB_SETROWS  (preliminaryWindows NT)

TB_SETSTATE  (preliminaryWindows NT)

TB_SETTOOLTIPS  (preliminaryWindows NT)

TCM_ADJUSTRECT  (preliminaryWindows NT)

TCM_DELETEALLITEMS  (preliminaryWindows NT)

TCM_DELETEITEM  (preliminaryWindows NT)

TCM_GETBKCOLOR  (preliminaryWindows NT)

TCM_GETCURFOCUS  (preliminaryWindows NT)

TCM_GETCURSEL  (preliminaryWindows NT)

TCM_GETIMAGELIST  (preliminaryWindows NT)

TCM_GETITEM  (preliminaryWindows NT)

TCM_GETITEMCOUNT  (preliminaryWindows NT)

TCM_GETITEMRECT  (preliminaryWindows NT)

TCM_GETROWCOUNT  (preliminaryWindows NT)

TCM_GETTOOLTIPS  (preliminaryWindows NT)

TCM_HITTEST  (preliminaryWindows NT)

TCM_INSERTITEM  (preliminaryWindows NT)

TCM_REMOVEIMAGE  (preliminaryWindows NT)

TCM_SETBKCOLOR  (preliminaryWindows NT)

TCM_SETCURSEL  (preliminaryWindows NT)

TCM_SETIMAGELIST  (preliminaryWindows NT)

TCM_SETITEM  (preliminaryWindows NT)

TCM_SETITEMEXTRA  (preliminaryWindows NT)

TCM_SETITEMSIZE  (preliminaryWindows NT)

TCM_SETPADDING  (preliminaryWindows NT)

TCM_SETTOOLTIPS  (preliminaryWindows NT)

TCN_KEYDOWN  (preliminaryWindows NT)

TCN_SELCHANGE  (preliminaryWindows NT)

TCN_SELCHANGING  (preliminaryWindows NT)

TTM_ACTIVATE  (preliminaryWindows NT)

TTM_ADDTOOL  (preliminaryWindows NT)

TTM_DELTOOL  (preliminaryWindows NT)

TTM_ENUMTOOLS  (preliminaryWindows NT)

TTM_GETCURRENTTOOL  (preliminaryWindows NT)

TTM_GETTEXT  (preliminaryWindows NT)

TTM_GETTOOLCOUNT  (preliminaryWindows NT)

TTM_GETTOOLINFO  (preliminaryWindows NT)

TTM_HITTEST  (preliminaryWindows NT)

TTM_NEWTOOLRECT  (preliminaryWindows NT)

TTM_RELAYEVENT  (preliminaryWindows NT)

TTM_SETDELAYTIME  (preliminaryWindows NT)

TTM_SETTOOLINFO  (preliminaryWindows NT)

TTM_UPDATETIPTEXT

TTM_WINDOWFROMPOINT

TTN_NEEDTEXT  (preliminaryWindows NT)

TTN_POP  (preliminaryWindows NT)

TTN_SHOW  (preliminaryWindows NT)

TVM_CREATEDRAGIMAGE  (preliminaryWindows NT)

TVM_DELETEITEM  (preliminaryWindows NT)

TVM_EDITLABEL  (preliminaryWindows NT)

TVM_ENDEDITLABELNOW  (preliminaryWindows NT)

TVM_ENSUREVISIBLE  (preliminaryWindows NT)

TVM_EXPAND  (preliminaryWindows NT)

TVM_GETCOUNT  (preliminaryWindows NT)

TVM_GETEDITCONTROL  (preliminaryWindows NT)

TVM_GETIMAGELIST  (preliminaryWindows NT)

TVM_GETINDENT  (preliminaryWindows NT)

TVM_GETISEARCHSTRING  (preliminaryWindows NT)

TVM_GETITEM  (preliminaryWindows NT)

TVM_GETITEMRECT  (preliminaryWindows NT)

TVM_GETNEXTITEM  (preliminaryWindows NT)

TVM_GETVISIBLECOUNT  (preliminaryWindows NT)

TVM_HITTEST  (preliminaryWindows NT)

TVM_INSERTITEM  (preliminaryWindows NT)

TVM_SELECTITEM  (preliminaryWindows NT)

TVM_SETIMAGELIST  (preliminaryWindows NT)

TVM_SETINDENT  (preliminaryWindows NT)

TVM_SETITEM  (preliminaryWindows NT)

TVM_SORTCHILDREN  (preliminaryWindows NT)

TVM_SORTCHILDRENCB  (preliminaryWindows NT)

TVN_BEGINDRAG  (preliminaryWindows NT)

TVN_BEGINLABELEDIT  (preliminaryWindows NT)

TVN_BEGINRDRAG  (preliminaryWindows NT)

TVN_DELETEITEM  (preliminaryWindows NT)

TVN_ENDLABELEDIT  (preliminaryWindows NT)

TVN_GETDISPINFO  (preliminaryWindows NT)

TVN_ITEMEXPANDED  (preliminaryWindows NT)

TVN_ITEMEXPANDING  (preliminaryWindows NT)

TVN_KEYDOWN  (preliminaryWindows NT)

TVN_SELCHANGED  (preliminaryWindows NT)

TVN_SELCHANGING  (preliminaryWindows NT)

TVN_SETDISPINFO  (preliminaryWindows NT)

U

UDM_GETACCEL  (preliminaryWindows NT)

UDM_GETBASE  (preliminaryWindows NT)

UDM_GETBUDDY  (preliminaryWindows NT)

UDM_GETPOS  (preliminaryWindows NT)

UDM_GETRANGE  (preliminaryWindows NT)

UDM_SETACCEL  (preliminaryWindows NT)

UDM_SETBASE  (preliminaryWindows NT)

UDM_SETBUDDY  (preliminaryWindows NT)

UDM_SETPOS  (preliminaryWindows NT)

UDM_SETRANGE  (preliminaryWindows NT)

UDN_DELTAPOS  (preliminaryWindows NT)

V

W

WM_ACTIVATE

WM_ACTIVATEAPP

WM_ASKCBFORMATNAME

WM_CANCELJOURNAL

WM_CANCELMODE

WM_CAPTURECHANGED  (preliminaryWindows 95)

WM_CHANGECBCHAIN

WM_CHAR

WM_CHARTOITEM

WM_CHILDACTIVATE

WM_CHOOSEFONT_GETLOGFONT

WM_CLEAR

WM_CLOSE

WM_COMMAND

WM_COMPACTING

WM_COMPAREITEM

WM_CONTEXTMENU  (preliminaryWindows NT)

WM_COPY

WM_COPYDATA

WM_CPL_LAUNCH

WM_CPL_LAUNCHED

WM_CREATE

WM_CTLCOLORBTN

WM_CTLCOLORDLG

WM_CTLCOLOREDIT

WM_CTLCOLORLISTBOX

WM_CTLCOLORMSGBOX

WM_CTLCOLORSCROLLBAR

WM_CTLCOLORSTATIC

WM_CUT

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

WM_DEADCHAR

WM_DELETEITEM

WM_DESTROY

WM_DESTROYCLIPBOARD

WM_DEVICECHANGE  (preliminaryWindows 95)

WM_DEVMODECHANGE

WM_DISPLAYCHANGE  (preliminaryWindows 95)

WM_DRAWCLIPBOARD

WM_DRAWITEM

WM_DROPFILES

WM_ENABLE

WM_ENDSESSION

WM_ENTERIDLE

WM_ENTERMENULOOP

WM_ENTERSIZEMOVE  (preliminaryWindows NT)

WM_ERASEBKGND

WM_EXITMENULOOP

WM_EXITSIZEMOVE  (preliminaryWindows NT)

WM_FONTCHANGE

WM_GETDLGCODE

WM_GETFONT

WM_GETHOTKEY

WM_GETICON  (preliminaryWindows 95)

WM_GETMINMAXINFO

WM_GETTEXT

WM_GETTEXTLENGTH

WM_HELP  (preliminaryWindows NT)

WM_HOTKEY

WM_HSCROLL

WM_HSCROLLCLIPBOARD

WM_ICONERASEBKGND

WM_IME_CHAR  (preliminaryWindows 95)

WM_IME_COMPOSITION  (preliminaryWindows 95)

WM_IME_COMPOSITIONFULL(preliminaryWindows 95)

WM_IME_CONTROL  (preliminaryWindows 95)

WM_IME_ENDCOMPOSITION(preliminaryWindows 95)

WM_IME_KEYDOWN

WM_IME_KEYUP

WM_IME_NOTIFY  (preliminaryWindows 95)

WM_IME_SELECT  (preliminaryWindows 95)

WM_IME_SETCONTEXT  (preliminaryWindows 95)

WM_IME_STARTCOMPOSITION(preliminaryWindows 95)

WM_INITDIALOG

WM_INITMENU

WM_INITMENUPOPUP

WM_INPUTLANGCHANGE  (preliminaryWindows 95)

WM_INPUTLANGCHANGEREQUEST  (preliminaryWindows 95)

WM_KEYDOWN

WM_KEYUP

WM_KILLFOCUS

WM_LBUTTONDBLCLK

WM_LBUTTONDOWN

WM_LBUTTONUP

WM_MBUTTONDBLCLK

WM_MBUTTONDOWN

WM_MBUTTONUP

WM_MDIACTIVATE

WM_MDICASCADE

WM_MDICREATE

WM_MDIDESTROY

WM_MDIGETACTIVE

WM_MDIICONARRANGE

WM_MDIMAXIMIZE

WM_MDINEXT

WM_MDIREFRESHMENU

WM_MDIRESTORE

WM_MDISETMENU

WM_MDITILE

WM_MEASUREITEM

WM_MENUCHAR

WM_MENUSELECT

WM_MOUSEACTIVATE

WM_MOUSEMOVE

WM_MOVE

WM_MOVING  (preliminaryWindows 95)

WM_NCACTIVATE

WM_NCCALCSIZE

WM_NCCREATE

WM_NCDESTROY

WM_NCHITTEST

WM_NCLBUTTONDBLCLK

WM_NCLBUTTONDOWN

WM_NCLBUTTONUP

WM_NCMBUTTONDBLCLK

WM_NCMBUTTONDOWN

WM_NCMBUTTONUP

WM_NCMOUSEMOVE

WM_NCPAINT

WM_NCRBUTTONDBLCLK

WM_NCRBUTTONDOWN

WM_NCRBUTTONUP

WM_NEXTDLGCTL

WM_NOTIFY  (preliminaryWindows NT)

WM_NOTIFYFORMAT  (preliminaryWindowsNT)

WM_PAINT

WM_PAINTCLIPBOARD

WM_PAINTICON

WM_PALETTECHANGED

WM_PALETTEISCHANGING

WM_PARENTNOTIFY

WM_PASTE

WM_POWER

WM_POWERBROADCAST  (preliminaryWindows 95)

WM_PRINT  (preliminaryWindows 95)

WM_PRINTCLIENT  (preliminaryWindows NT)

WM_QUERYDRAGICON

WM_QUERYENDSESSION

WM_QUERYNEWPALETTE

WM_QUERYOPEN

WM_QUEUESYNC

WM_QUIT

WM_RASDIALEVENT

WM_RBUTTONDBLCLK

WM_RBUTTONDOWN

WM_RBUTTONUP

WM_RENDERALLFORMATS

WM_RENDERFORMAT

WM_SETCURSOR

WM_SETFOCUS

WM_SETFONT

WM_SETHOTKEY

WM_SETICON  (preliminaryWindows 95)

WM_SETREDRAW

WM_SETTEXT

WM_SETTINGCHANGE  (preliminaryWindows 95)

WM_SHOWWINDOW

WM_SIZE

WM_SIZECLIPBOARD

WM_SIZING  (preliminaryWindows 95)

WM_SPOOLERSTATUS

WM_STYLECHANGED  (preliminaryWindows NT)

WM_STYLECHANGING  (preliminaryWindows NT)

WM_SYSCHAR

WM_SYSCOLORCHANGE

WM_SYSCOMMAND

WM_SYSDEADCHAR

WM_SYSKEYDOWN

WM_SYSKEYUP

WM_TCARD  (preliminaryWindows 95)

WM_TIMECHANGE

WM_TIMER

WM_UNDO

WM_USER

WM_USERCHANGED  (preliminaryWindows 95)

WM_VKEYTOITEM

WM_VSCROLL

WM_VSCROLLCLIPBOARD

WM_WINDOWPOSCHANGED

WM_WINDOWPOSCHANGING

WM_WININICHANGE

X

XTYP_ADVDATA

XTYP_ADVREQ

XTYP_ADVSTART

XTYP_ADVSTOP

XTYP_CONNECT

XTYP_CONNECT_CONFIRM

XTYP_DISCONNECT

XTYP_ERROR

XTYP_EXECUTE

XTYP_MONITOR

XTYP_POKE

XTYP_REGISTER

XTYP_REQUEST

XTYP_UNREGISTER

XTYP_WILDCONNECT

XTYP_XACT_COMPLETE

Y

Z


Win32 API Help Contents: Macros
Macros

Animate_Create  (preliminaryWindows NT)

CMYK  (preliminaryWindows 95)

FORWARD_WM_NOTIFY  (preliminaryWindows NT)

GetBValue

GetCValue  (preliminaryWindows 95)

GetGValue

GetKValue  (preliminaryWindows 95)

GetMValue  (preliminaryWindows 95)

GetRValue

GetYValue  (preliminaryWindows 95)

HANDLE_WM_NOTIFY  (preliminaryWindows NT)

HIBYTE

HIWORD

INDEXTOOVERLAYMASK  (preliminaryWindows NT)

INDEXTOSTATEIMAGEMASK  (preliminaryWindows NT)

LANGIDFROMLCID

LOBYTE

LOWORD

MAKEINTATOM

MAKEINTRESOURCE

MAKELANGID

MAKELCID

MAKELONG

MAKELPARAM

MAKELRESULT

MAKEPOINTS

MAKEROP4

MAKEWORD

MAKEWPARAM

max

min

PALETTEINDEX

PALETTERGB

POINTSTOPOINT

POINTTOPOINTS

PRIMARYLANGID

RGB

SORTIDFROMLCID

SUBLANGID

TEXT Macro


Win32 API Help Contents: Structures
Structures

A

ABC

ABCFLOAT

ACCEL

ACCESS_ALLOWED_ACE

ACCESS_DENIED_ACE

ACCESS_MASK

ACCESSTIMEOUT

ACE

ACE_HEADER

ACL

ACL_REVISION_INFORMATION

ACL_SIZE_INFORMATION

ACTION_HEADER

ADAPTER_STATUS

ADDJOB_INFO_1

ANIMATIONINFO

APPBARDATA

B

BITMAP

BITMAPCOREHEADER

BITMAPCOREINFO

BITMAPFILEHEADER

BITMAPINFO

BITMAPINFOHEADER

BITMAPV4HEADER  (preliminaryWindows 95)

BLOB

BROWSEINFO

BY_HANDLE_FILE_INFORMATION

C

CANDIDATEFORM  (preliminaryWindows 95)

CANDIDATELIST  (preliminaryWindows 95)

CBT_CREATEWND

CBTACTIVATESTRUCT

CHAR_INFO

CHARFORMAT  (preliminaryWindows NT)

CHARRANGE  (preliminaryWindows NT)

CHARSET

CHARSETINFO  (preliminaryWindows 95)

CHOOSECOLOR

CHOOSEFONT

CIDA

CIEXYZ  (preliminaryWindows 95)

CIEXYZTRIPLE  (preliminaryWindows 95)

CLIENTCREATESTRUCT

CMINVOKECOMMANDINFO

COLORADJUSTMENT

COLORMAP  (preliminaryWindows NT)

COLORREF

COMMCONFIG  (preliminaryWindows 95)

COMMPROP

COMMTIMEOUTS

COMPAREITEMSTRUCT

COMPOSITIONFORM  (preliminaryWindows 95)

COMSTAT

CONSOLE_CURSOR_INFO

CONSOLE_SCREEN_BUFFER_INFO

CONTEXT

CONVCONTEXT

CONVINFO

COORD

COPYDATASTRUCT

CPINFO

CPLINFO

CREATE_PROCESS_DEBUG_INFO

CREATE_THREAD_DEBUG_INFO

CREATESTRUCT

CSADDR_INFO

CURRENCYFMT

CURSORSHAPE

CWPRETSTRUCT  (preliminaryWindows 95)

CWPSTRUCT

D

DATATYPES_INFO_1

DCB

DDEACK

DDEADVISE

DDEDATA

DDELN

DDEML_MSG_HOOK_DATA

DDEPOKE

DDEUP

DEBUGHOOKINFO

DEBUG_EVENT

DELETEITEMSTRUCT

DEVMODE

DEVNAMES

DEV_BROADCAST_HDR  (preliminaryWindows 95)

DEV_BROADCAST_OEM  (preliminaryWindows 95)

DEV_BROADCAST_PORT  (preliminaryWindows 95)

_DEV_BROADCAST_USERDEFINED

DEV_BROADCAST_VOLUME  (preliminaryWindows 95)

DIBSECTION

DISK_GEOMETRY

DISK_PERFORMANCE

DLGITEMTEMPLATE

DLGTEMPLATE

DOCINFO

DOC_INFO_1

DOC_INFO_2  (preliminaryWindows 95)

DRAGLISTINFO  (preliminaryWindows NT)

DRAWITEMSTRUCT

DRAWTEXTPARAMS  (preliminaryWindows 95)

DRIVER_INFO_1

DRIVER_INFO_2

DRIVER_INFO_3  (preliminaryWindows 95)

DRIVE_LAYOUT_INFORMATION

E

EDITSTREAM  (preliminaryWindows NT)

EMR

EMRANGLEARC

EMRARC, EMRARCTO, EMRCHORD, EMRPIE

EMRBITBLT

EMRCREATEBRUSHINDIRECT

EMRCREATECOLORSPACE  (preliminaryWindows 95)

EMRCREATEDIBPATTERNBRUSHPT

EMRCREATEMONOBRUSH

EMRCREATEPALETTE

EMRCREATEPEN

EMRELLIPSE, EMRRECTANGLE

EMREOF

EMREXCLUDECLIPRECT, EMRINTERSECTCLIPRECT

EMREXTCREATEFONTINDIRECTW

EMREXTCREATEPEN

EMREXTFLOODFILL

EMREXTSELECTCLIPRGN

EMREXTTEXTOUTA, EMREXTTEXTOUTW

EMRFILLPATH, EMRSTROKEANDFILLPATH, EMRSTROKEPATH

EMRFILLRGN

EMRFORMAT

EMRFRAMERGN

EMRGDICOMMENT

EMRINVERTRGN, EMRPAINTRGN

EMRLINETO, EMRMOVETOEX

EMRMASKBLT

EMRMODIFYWORLDTRANSFORM

EMROFFSETCLIPRGN

EMRPLGBLT

EMRPOLYDRAW

EMRPOLYDRAW16

EMRPOLYLINE, EMRPOLYBEZIER, EMRPOLYGON, EMRPOLYBEZIERTO, EMRPOLYLINETO

EMRPOLYLINE16, EMRPOLYBEZIER16, EMRPOLYGON16, EMRPOLYBEZIERTO16, EMRPOLYLINETO16

EMRPOLYPOLYLINE, EMRPOLYPOLYGON

EMRPOLYPOLYLINE16, EMRPOLYPOLYGON16

EMRPOLYTEXTOUTA, EMRPOLYTEXTOUTW

EMRRESIZEPALETTE

EMRRESTOREDC

EMRROUNDRECT

EMRSCALEVIEWPORTEXTEX, EMRSCALEWINDOWEXTEX

EMRSELECTCOLORSPACE, EMRDELETECOLORSPACE  (preliminaryWindows 95)

EMRSELECTOBJECT, EMRDELETEOBJECT

EMRSELECTPALETTE

EMRSETARCDIRECTION

EMRSETBKCOLOR, EMRSETTEXTCOLOR

EMRSETCOLORADJUSTMENT

EMRSETDIBITSTODEVICE

EMRSETMAPPERFLAGS

EMRSETMITERLIMIT

EMRSETPALETTEENTRIES

EMRSETPIXELV

EMRSETVIEWPORTEXTEX, EMRSETWINDOWEXTEX

EMRSETVIEWPORTORGEX, EMRSETWINDOWORGEX, EMRSETBRUSHORGEX

EMRSETWORLDTRANSFORM

EMRSTRETCHBLT

EMRSTRETCHDIBITS

EMRTEXT

ENDROPFILES  (preliminaryWindows NT)

ENHMETAHEADER

ENHMETARECORD

ENPROTECTED  (preliminaryWindows NT)

ENUMLOGFONT

ENUMLOGFONTEX  (preliminaryWindows 95)

ENUM_SERVICE_STATUS

EVENTLOGRECORD

EVENTMSG

EXCEPTION_DEBUG_INFO

EXCEPTION_POINTERS

EXCEPTION_RECORD

EXIT_PROCESS_DEBUG_INFO

EXIT_THREAD_DEBUG_INFO

EXTLOGFONT

EXTLOGPEN

EXT_BUTTON

Enhanced Metafile Records with No Parameters

Enhanced Metafile Records with One Parameter

F

FILETIME

FILTERKEYS

FINDREPLACE

FINDTEXT  (preliminaryWindows NT)

FIND_NAME_BUFFER

FIND_NAME_HEADER

FIXED

FMS_GETDRIVEINFO

FMS_GETFILESEL

FMS_LOAD

FMS_TOOLBARLOAD

FOCUS_EVENT_RECORD

FONTSIGNATURE  (preliminaryWindows 95)

FORMATRANGE  (preliminaryWindows NT)

FORMAT_PARAMETERS

FORM_INFO_1

G

GCP_RESULTS  (preliminaryWindows 95)

GENERIC_MAPPING

GLYPHMETRICS

H

HANDLETABLE

HD_HITTESTINFO  (preliminaryWindows NT)

HD_ITEM  (preliminaryWindows NT)

HD_LAYOUT  (preliminaryWindows NT)

HD_NOTIFY  (preliminaryWindows NT)

HELPINFO

HELPWININFO

HIGHCONTRAST  (preliminaryWindows 95)

HSZPAIR

I

ICONINFO

ICONMETRICS

IMAGEINFO  (preliminaryWindows NT)

INPUT_RECORD

ITEMIDLIST

J

JOB_INFO_1

JOB_INFO_2

K

KERNINGPAIR

KEY_EVENT_RECORD

L

LANA_ENUM

LARGE_INTEGER

LDT_ENTRY

LIST_ENTRY

LOAD_DLL_DEBUG_INFO

LOCALESIGNATURE  (preliminaryWindows 95)

LOGBRUSH

LOGCOLORSPACE  (preliminaryWindows 95)

LOGFONT

LOGPALETTE

LOGPEN

LUID

LUID_AND_ATTRIBUTES

LV_COLUMN  (preliminaryWindows NT)

LV_DISPINFO  (preliminaryWindows NT)

LV_FINDINFO  (preliminaryWindows NT)

LV_HITTESTINFO  (preliminaryWindows NT)

LV_ITEM  (preliminaryWindows NT)

LV_KEYDOWN  (preliminaryWindows NT)

M

MAT2

MDICREATESTRUCT

MEASUREITEMSTRUCT

MEMORYSTATUS

MEMORY_BASIC_INFORMATION

MENUEX_TEMPLATE_HEADER  (preliminaryWindows 95)

MENUEX_TEMPLATE_ITEM  (preliminaryWindows 95)

MENUITEMINFO  (preliminaryWindows 95)

MENUITEMTEMPLATE

MENUITEMTEMPLATEHEADER

MENU_EVENT_RECORD

METAFILEPICT

METAHEADER

METARECORD

MINIMIZEDMETRICS

MINMAXINFO

MODEMDEVCAPS  (preliminaryWindows 95)

MODEMSETTINGS  (preliminaryWindows 95)

MONCBSTRUCT

MONCONVSTRUCT

MONERRSTRUCT

MONHSZSTRUCT

MONITOR_INFO_1

MONITOR_INFO_2

MONLINKSTRUCT

MONMSGSTRUCT

MOUSEHOOKSTRUCT

MOUSEKEYS

MOUSE_EVENT_RECORD

MSG

MSGBOXPARAMS  (preliminaryWindows 95)

MSGFILTER  (preliminaryWindows NT)

MULTIKEYHELP

N

NAME_BUFFER

NCB

NCCALCSIZE_PARAMS

NDDESHAREINFO

NETRESOURCE

NEWCPLINFO

NEWTEXTMETRIC

NEWTEXTMETRICEX  (preliminaryWindows 95)

NMHDR  (preliminaryWindows NT)

NM_LISTVIEW  (preliminaryWindows NT)

NM_TREEVIEW  (preliminaryWindows NT)

NM_UPDOWN  (preliminaryWindows NT)

NONCLIENTMETRICS

NS_SERVICE_INFO

NUMBERFMT

O

OFSTRUCT

OPENFILENAME

OSVERSIONINFO

OUTLINETEXTMETRIC

OUTPUT_DEBUG_STRING_INFO

OVERLAPPED

P

PAINTSTRUCT

PALETTEENTRY

PANOSE

PARAFORMAT  (preliminaryWindows NT)

PARTITION_INFORMATION

PERF_COUNTER_BLOCK

PERF_COUNTER_DEFINITION

PERF_DATA_BLOCK

PERF_INSTANCE_DEFINITION

PERF_OBJECT_TYPE

POINT

POINTFX

POINTL

POINTS

POLYTEXT

PORT_INFO_1

PORT_INFO_2  (preliminaryWindows 95)

PREVENT_MEDIA_REMOVAL

PRINTDLG

PRINTER_DEFAULTS

PRINTER_INFO_1

PRINTER_INFO_2

PRINTER_INFO_3

PRINTER_INFO_4

PRINTER_INFO_5  (preliminaryWindows 95)

PRINTER_NOTIFY_INFO

PRINTER_NOTIFY_INFO_DATA

PRINTER_NOTIFY_OPTIONS

PRINTER_NOTIFY_OPTIONS_TYPE

PRINTPROCESSOR_INFO_1

PRIVILEGE_SET

PROCESS_HEAP_ENTRY

PROCESS_INFORMATION

PROPSHEETHEADER  (preliminaryWindows NT)

PROPSHEETPAGE  (preliminaryWindows NT)

PROTOCOL_INFO

PROVIDOR_INFO_1

PSHNOTIFY

Q

QUERY_SERVICE_CONFIG

QUERY_SERVICE_LOCK_STATUS

R

RASAMB

RASCONN

RASCONNSTATUS

RASDIALEXTENSIONS

RASDIALPARAMS

RASENTRYNAME

RASPPPIP

RASPPPIPX

RASPPPNBF

RASTERIZER_STATUS

REASSIGN_BLOCKS

RECT

RECTL

REMOTE_NAME_INFO

REQRESIZE  (preliminaryWindows NT)

RGBQUAD

RGBTRIPLE

RGNDATA

RGNDATAHEADER

RIP_INFO

S

SCROLLINFO  (preliminaryWindows NT)

SECURITY_ATTRIBUTES

SECURITY_DESCRIPTOR

SECURITY_DESCRIPTOR_CONTROL

SECURITY_INFORMATION

SECURITY_QUALITY_OF_SERVICE

SELCHANGE  (preliminaryWindows NT)

SERIALKEYS  (preliminaryWindows NT)

SERVICE_ADDRESS

SERVICE_ADDRESSES

SERVICE_INFO

SERVICE_STATUS

SERVICE_TABLE_ENTRY

SERVICE_TYPE_INFO_ABS

SERVICE_TYPE_VALUE_ABS

SESSION_BUFFER

SESSION_HEADER

SET_PARTITION_INFORMATION

SHCONTF

SHFILEINFO

SHFILEOPSTRUCT

SHGNO

SHITEMID

SHNAMEMAPPING

SID

SID_AND_ATTRIBUTES

SID_IDENTIFIER_AUTHORITY

SINGLE_LIST_ENTRY

SIZE

SMALL_RECT

SOUNDSENTRY

STARTUPINFO

STICKYKEYS

STRRET

STYLEBUF  (preliminaryWindows 95)

STYLESTRUCT

SYSTEMTIME

SYSTEM_ALARM_ACE

SYSTEM_AUDIT_ACE

SYSTEM_INFO

SYSTEM_POWER_STATUS  (preliminaryWindows 95)

String

StringFileInfo

StringTable

T

TAPE_ERASE

TAPE_GET_DRIVE_PARAMETERS

TAPE_GET_MEDIA_PARAMETERS

TAPE_GET_POSITION

TAPE_PREPARE

TAPE_SET_DRIVE_PARAMETERS

TAPE_SET_MEDIA_PARAMETERS

TAPE_SET_POSITION

TAPE_WRITE_MARKS

TBADDBITMAP  (preliminaryWindows NT)

TBBUTTON  (preliminaryWindows NT)

TBNOTIFY  (preliminaryWindows NT)

TBSAVEPARAMS  (preliminaryWindows NT)

TC_HITTESTINFO  (preliminaryWindows NT)

TC_ITEM  (preliminaryWindows NT)

TC_ITEMHEADER  (preliminaryWindows NT)

TC_KEYDOWN  (preliminaryWindows NT)

TEXTMETRIC

TEXTRANGE  (preliminaryWindows NT)

TIME_ZONE_INFORMATION

TOGGLEKEYS

TOKEN_CONTROL

TOKEN_DEFAULT_DACL

TOKEN_GROUPS

TOKEN_OWNER

TOKEN_PRIMARY_GROUP

TOKEN_PRIVILEGES

TOKEN_SOURCE

TOKEN_STATISTICS

TOKEN_USER

TOOLINFO  (preliminaryWindows NT)

TOOLTIPTEXT  (preliminaryWindows NT)

TPMPARAMS  (preliminaryWindows 95)

TRANSMIT_FILE_BUFFERS  (preliminaryWindows NT)

TTHITTESTINFO  (preliminaryWindows NT)

TTPOLYCURVE

TTPOLYGONHEADER

TV_DISPINFO  (preliminaryWindows NT)

TV_HITTESTINFO  (preliminaryWindows NT)

TV_INSERTSTRUCT  (preliminaryWindows NT)

TV_ITEM  (preliminaryWindows NT)

TV_KEYDOWN  (preliminaryWindows NT)

TV_SORTCB  (preliminaryWindows NT)

U

UDACCEL  (preliminaryWindows NT)

ULARGE_INTEGER

UNIVERSAL_NAME_INFO

UNLOAD_DLL_DEBUG_INFO

USEROBJECTFLAGS  (preliminaryWindows NT)

V

VERIFY_INFORMATION

VS_FIXEDFILEINFO

VS_VERSION_INFO

Var

VarFileInfo

W

WIN32_FIND_DATA

WIN32_STREAM_ID

WINDOWPLACEMENT

WINDOWPOS

WINDOW_BUFFER_SIZE_RECORD

WNDCLASS

WNDCLASSEX

X

XFORM

Y

Z


Win32 API Help Contents: Enumeration Types
Enumeration Types

ACL_INFORMATION_CLASS

MEDIA_TYPE

RASCONNSTATE

RASPROJECTION

SECURITY_IMPERSONATION_LEVEL

SID_NAME_USE

TOKEN_INFORMATION_CLASS

TOKEN_TYPE


Win32 API Help Contents: Interfaces
Interfaces

IContextMenu

IContextMenu::GetCommandString

IContextMenu::InvokeCommand

IContextMenu::QueryContextMenu

ICopyHook

ICopyHook::CopyCallback

IEnumIDList

IEnumIDList::Clone

IEnumIDList::Next

IEnumIDList::Reset

IEnumIDList::Skip

IExtractIcon

IExtractIcon::ExtractIcon

IExtractIcon::GetIconLocation

IRichEditOle

IRichEditOle::ActivateAs

IRichEditOle::ContextSensitiveHelp

IRichEditOle::ConvertObject

IRichEditOle::GetClientSite

IRichEditOle::GetClipboardData

IRichEditOle::GetLinkCount

IRichEditOle::GetObject

IRichEditOle::GetObjectCount

IRichEditOle::HandsOffStorage

IRichEditOle::ImportDataObject

IRichEditOle::InPlaceDeactivate

IRichEditOle::InsertObject

IRichEditOle::SaveCompleted

IRichEditOle::SetDvaspect

IRichEditOle::SetHostNames

IRichEditOle::SetLinkAvailable

IRichEditOleCallback

IRichEditOleCallback::ContextSensitiveHelp

IRichEditOleCallback::DeleteObject

IRichEditOleCallback::GetClipboardData

IRichEditOleCallback::GetContextMenu

IRichEditOleCallback::GetDragDropEffect

IRichEditOleCallback::GetInPlaceContext

IRichEditOleCallback::GetNewStorage

IRichEditOleCallback::QueryAcceptData

IRichEditOleCallback::QueryInsertObject

IRichEditOleCallback::ShowContainerUI

IShellPropSheetExt

IShellPropSheetExt::AddPages

IShellPropSheetExt::ReplacePage

IShellExtInit

IShellExtInit::Initialize

IShellLink

IShellLink::GetArguments

IShellLink::GetDescription

IShellLink::GetHotkey

IShellLink::GetIconLocation

IShellLink::GetIDList

IShellLink::GetPath

IShellLink::GetShowCmd

IShellLink::GetWorkingDirectory

IShellLink::Resolve

IShellLink::SetArguments

IShellLink::SetDescription

IShellLink::SetHotkey

IShellLink::SetIconLocation

IShellLink::SetIDList

IShellLink::SetPath

IShellLink::SetRelativePath

IShellLink::SetShowCmd

IShellLink::SetWorkingDirectory

IShellFolder

IShellFolder::BindToObject

IShellFolder::BindToStorage

IShellFolder::CompareIDs

IShellFolder::CreateViewObject

IShellFolder::EnumObjects

IShellFolder::GetAttributesOf

IShellFolder::GetDisplayNameOf

IShellFolder::GetUIObjectOf

IShellFolder::ParseDisplayName

IShellFolder::SetNameOf


Data Types

Various simple data types define the size and meaning of parameters, return values, and members associated with the functions, messages, and structures of Microsoft Windows. The following table contains character, integer, and Boolean types; pointer types; and handles. The character, integer, and Boolean types are common to most C compilers. Many of the pointer-type names begin with a prefix of P or LP. A Windows-based application uses a handle to refer to a resource that has been loaded into memory. Windows provides access to these resources through internally maintained tables that contain individual entries for each handle. Each entry in the handle table contains the address of the resource and a means of identifying the resource type.

Type	Definition
ABORTPROC	Pointer to an application-defined callback function that the operating system calls when a print job is to be cancelled during spooling. See AbortProc for information on functions of this type.
APPLET_PROC	Pointer to a library-defined callback function that is the entry point for a Control Panel application. See CplApplet for information on functions of this type.
ATOM	Atom (a reference to a character string in an atom table).
BOOL	Boolean variable (should be TRUE or FALSE).
BOOLEAN	Boolean variable (should be TRUE or FALSE).
BYTE	Byte (8 bits).
CCHAR	Windows character.
CHAR	Windows character.
COLORREF	Red, green, blue (RGB) color value (32 bits).
CONST	Variable whose value is to remain constant during execution.
CRITICAL_SECTION	Critical-section object.
CTRYID	Country identifier.
DLGPROC	Pointer to an application-defined dialog box callback procedure.
DWORD	Doubleword (32 bits).
DWORDLONG	Double (64 bits).
EDITWORDBREAKPROC	Pointer to an application-defined callback function that the operating system calls when a multiline edit control needs to break a line of text. See EditWordBreakProc for information on functions of this type.
ENHMFENUMPROC	Pointer to an application-defined callback function that enumerates enhanced-metafile records.
ENUMRESLANGPROC	Pointer to an application-defined callback function that enumerates resource languages.
ENUMRESNAMEPROC	Pointer to an application-defined callback function that enumerates resource names.
ENUMRESTYPEPROC	Pointer to an application-defined callback function that enumerates resource types.
FARPROC	Pointer to a callback function.
FLOAT	Floating-point variable.
FONTENUMPROC	Pointer to an application-defined callback function that enumerates fonts.
GLOBALHANDLE	Handle of a global memory block.
GOBJENUMPROC	Pointer to an application-defined callback function that enumerates graphics device interface (GDI) objects.
GRAYSTRINGPROC	Pointer to an application-defined callback function that draws gray text.
HACCEL	Handle of an accelerator table.
HANDLE	Handle of an object.
HBITMAP	Handle of a bitmap.
HBRUSH	Handle of a brush.
HCOLORSPACE	Windows 95 only: Handle of a logical color space.
HCONV	Handle of a dynamic data exchange (DDE) conversation.
HCONVLIST	Handle of a DDE conversation list.
HCURSOR	Handle of a cursor.
HDC	Handle of a device context (DC).
HDDEDATA	Handle of DDE data.
HDWP	Handle of a deferred window position structure.
HENHMETAFILE	Handle of an enhanced metafile.
HFILE	Handle of a file.
HFONT	Handle of a font.
HGDIOBJ	Handle of a GDI object.
HGLOBAL	Handle of a global memory block.
HHOOK	Handle of a hook.
HICON	Handle of an icon.
HIMAGELIST	Handle to an image list.
HINSTANCE	Handle of an instance.
HKEY	Handle of a registry key.
HKL	Windows 95 only: Handle of a keyboard layout.
HLOCAL	Handle of a local memory block.
HMENU	Handle of a menu.
HMETAFILE	Handle of a metafile.
HMODULE	Handle of a module.
HOOKPROC	Pointer to an application-defined hook function.
HPALETTE	Handle of a palette.
HPEN	Handle of a pen.
HRGN	Handle of a region.
HRSRC	Handle of a resource.
HSZ	Handle of a DDE string.
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.
LOCALHANDLE	Handle of a local memory block.
LONG	32-bit signed value.
LONGLONG	Double (64 bits).
LP	Pointer to a null-terminated Unicode™ string.
LPARAM	32-bit message parameter.
LPBOOL	Pointer to a Boolean variable.
LPBYTE	Pointer to a byte.
LPCCH	Pointer to a constant Windows character.
LPCCHOOKPROC	Pointer to an application-defined hook function.
LPCFHOOKPROC	Pointer to an application-defined hook function.
LPCH	Pointer to a Windows character.
LPCOLORREF	Pointer to a COLORREF value.
LPCRITICAL_SECTION	Pointer to a critical-section object.
LPCSTR	Pointer to a constant null-terminated Windows character string.
LPCTSTR	Pointer to a constant null-terminated Unicode or Windows character string.
LPCWCH	Pointer to a constant null-terminated Unicode character.
LPCWSTR	Pointer to a constant null-terminated Unicode character string.
LPDWORD	Pointer to an unsigned doubleword (32 bits).
LPFRHOOKPROC	Pointer to an application-defined hook function.
LPHANDLE	Pointer to a handle.
LPHANDLER_FUNCTION	Pointer to a handler function.
LPINT	Pointer to a signed integer.
LPLONG	Pointer to a signed long (32 bits).
LPOFNHOOKPROC	Pointer to an application-defined hook function.
LPPRINTHOOKPROC	Pointer to an application-defined hook function.
LPSETUPHOOKPROC	Pointer to an application-defined hook function.
LPSTR	Pointer to a null-terminated Windows character string.
LPTCH	Pointer to a Unicode character or a Windows character.
LPTSTR	Pointer to a null-terminated Windows or Unicode character string.
LRESULT	Signed result of message processing.
LPVOID	Pointer to any type.
LPWCH	Pointer to a Unicode character.
LPWORD	Pointer to an unsigned word (16 bits).
LPWSTR	Pointer to a null-terminated Unicode character string.
LUID	Locally unique identifier.
MFENUMPROC	Pointer to an application-defined callback function that enumerates metafile records.
NPSTR	Pointer to a null-terminated Windows character string.
NWPSTR	Pointer to a null-terminated Unicode string.
PBOOL	Pointer to a Boolean variable.
PBOOLEAN	Pointer to a Boolean variable.
PBYTE	Pointer to a byte.
PCCH	Pointer to a constant Windows character.
PCH	Pointer to a Windows character.
PCHAR	Pointer to a Windows character.
PCRITICAL_SECTION	Pointer to a critical-section object.
PCSTR	Pointer to a constant null-terminated Windows character string.
PCWCH	Pointer to a constant Unicode character.
PCWSTR	Pointer to a constant null-terminated Unicode character string.
PDWORD	Pointer to an unsigned doubleword (32 bits).
PFLOAT	Pointer to a floating-point variable.
PFNCALLBACK	Pointer to a callback function.
PHANDLE	Pointer to a handle.
PHANDLER_ROUTINE	Pointer to a handler routine.
PHKEY	Pointer to a registry key.
PINT	Pointer to a signed integer.
PLCID	Pointer to a locale identifier.
PLONG	Pointer to a signed long (32 bits).
PLUID	Pointer to a locally unique identifier (LUID).
PROC	Pointer to a callback function.
PROPENUMPROC	Pointer to an application-defined callback function that enumerates window properties. See PropEnumProc for information on functions of this type.
PROPENUMPROCEX	Pointer to an application-defined callback function that enumerates window properties. See PropEnumProcEx for information on functions of this type.
PSHORT	Pointer to a signed short (16 bits).
PSID	Pointer to a security identifier (SID).
PSTR	Pointer to a null-terminated Windows character string.
PSZ	Pointer to a null-terminated Windows character string.
PTBYTE	Pointer to a Windows or Unicode character.
PTCH	Pointer to a Windows or Unicode character.
PTCHAR	Pointer to a Windows or Unicode character.
PTSTR	Pointer to a null-terminated Windows or Unicode character string.
PUCHAR	Pointer to an unsigned Windows character.
PUINT	Pointer to an unsigned integer.
PULONG	Pointer to an unsigned long (32 bits).
PUSHORT	Pointer to an unsigned short (16 bits).
PVOID	Pointer to any type.
PWCH	Pointer to a Unicode character.
PWCHAR	Pointer to a Unicode character.
PWORD	Pointer to an unsigned word (16 bits).
PWSTR	Pointer to a null-terminated Unicode character string.
REGSAM	Security access mask for registry key.
SC_HANDLE	Handle of a service.
SENDASYNCPROC	Pointer to an application-defined callback function that the operating system calls when the SendMessageCallback function is called. The system passes the message to the callback function after passing the message to the destination window procedure. See SendAsyncProc for information on functions of this type.
SERVICE_STATUS_HANDLE	Handle of a service status value.
SHORT	Short integer.
SPHANDLE	Pointer to a handle.
TBYTE	Windows or Unicode character.
TCHAR	Unicode character or Windows character.
TIMERPROC	Pointer to an application-defined timer callback function.
UCHAR	Unsigned Windows character.
UINT	Unsigned integer.
ULONG	Unsigned long integer (32 bits).
USHORT	Unsigned short integer (16 bits).
VOID	Any type.
WCHAR	Unicode character.
WNDENUMPROC	Pointer to an application-defined callback function that enumerates windows.
WNDPROC	Pointer to an application-defined window procedure.
WORD	Unsigned word (16 bits).
WPARAM	32-bit message parameter.
YIELDPROC	Pointer to a yield callback function.


ACL_INFORMATION_CLASS

typedef enum _ACL_INFORMATION_CLASS { // aclic

    AclRevisionInformation = 1,    // ACL revision information

    AclSizeInformation             // ACL size information

} ACL_INFORMATION_CLASS;

The ACL_INFORMATION_CLASS enumeration type contains values that specify the type of information being assigned to or retrieved from an access-control list (ACL).

See Also

ACL, ACL_REVISION_INFORMATION, ACL_SIZE_INFORMATION, GetAclInformation, SetAclInformation


MEDIA_TYPE

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 enumeration type contains values that specify various forms of device media. The comments above explain the enumerators.

Remarks

The MediaType member of the DISK_GEOMETRY data structure is of type MEDIA_TYPE. The DeviceIoControl function receives a DISK_GEOMETRY structure in response to an IOCTL_DISK_GET_DRIVE_GEOMETRY device I/O operation. The DeviceIoControl function receives an array of DISK_GEOMETRY structures in response to an IOCTL_DISK_GET_MEDIA_TYPES device I/O operation.

See Also

DeviceIoControl, DISK_GEOMETRY, IOCTL_DISK_GET_DRIVE_GEOMETRY, IOCTL_DISK_GET_MEDIA_TYPES


RASCONNSTATE

typedef enum _RASCONNSTATE {

    RASCS_OpenPort = 0,

    RASCS_PortOpened,

    RASCS_ConnectDevice,

    RASCS_DeviceConnected,

    RASCS_AllDevicesConnected,

    RASCS_Authenticate,

    RASCS_AuthNotify,

    RASCS_AuthRetry,

    RASCS_AuthCallback,

    RASCS_AuthChangePassword,

    RASCS_AuthProject,

    RASCS_AuthLinkSpeed,

    RASCS_AuthAck,

    RASCS_ReAuthenticate,

    RASCS_Authenticated,

    RASCS_PrepareForCallback,

    RASCS_WaitForModemReset,

    RASCS_WaitForCallback,
    RASCS_Projected,

    RASCS_Interactive = RASCS_PAUSED,

    RASCS_RetryAuthentication,

    RASCS_CallbackSetByCaller,

    RASCS_PasswordExpired,

    RASCS_Connected = RASCS_DONE,

    RASCS_Disconnected

} RASCONNSTATE ;

The RASCONNSTATE enumeration type contains values that specify the states that may occur when connecting by using the RasDial function.

A RASCONNSTATE enumerator value is returned as part of a RASCONNSTATUS structure, which is retrieved by calls to the RasGetConnectStatus function.

The enumerator values are listed here in the general order in which 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 dial-up X.25 PAD connection, the pair will be called first for the modem, then for the PAD. If a preconnect switch is configured, the pair will be called for the switch before any other devices connect. Likewise, the pair will be called for a postconnect switch after any other devices connect.
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 and receive data on the LAN on behalf of the client. For example, the remote access server might need to add a NetBIOS name that corresponds to the client's computer name.  • Callback processing in which the client hangs up and the server calls back. (The user needs special permissions on the remote access server for this.)  • Calculating the link speed. This is necessary to correctly set transport timeouts to match the relatively slow speed of the remote link.
RASCS_AuthNotify	An authentication event has occurred. If dwError is zero, this event will be immediately followed by one of the more specific authentication states following. If dwError is nonzero, authentication has failed, and the error value indicates why.
RASCS_AuthRetry	The client has requested another validation attempt with a new username/password/domain. This state does not occur in Windows NT version 3.1.
RASCS_AuthCallback	The remote access server has requested a callback number. This occurs only if the user has "Set By Caller" callback privilege on the server.
RASCS_AuthChangePassword	The client has requested to change the password on the account. This state does not occur in Windows NT version 3.1.
RASCS_AuthProject	The projection phase is starting.
RASCS_AuthLinkSpeed	The link-speed calculation phase is starting.
RASCS_AuthAck	An authentication request is being acknowledged.
RASCS_ReAuthenticate	Reauthentication (after callback) is starting.
RASCS_Authenticated	The client has successfully completed authentication.
RASCS_PrepareForCallback	The line is about to disconnect in preparation for callback.
RASCS_WaitForModemReset	The client is delaying in order to give the modem time to reset itself in preparation for callback.
RASCS_WaitForCallback	The client is waiting for an incoming call from the remote access server.
RASCS_Projected	This state occurs after the RASCS_AuthProject state. It indicates that projection result information is available. You can access the projection result information by calling RasGetProjectionInfo.
RASCS_Interactive	This state corresponds to the terminal state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_RetryAuthentication	This state corresponds to the retry authentication state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_CallbackSetByCaller	This state corresponds to the Callback state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_PasswordExpired	This state corresponds to the change password state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.
RASCS_Connected	Successful connection.
RASCS_Disconnected	Disconnection or failed connection.
Remarks

The connection process states are divided into three classes: running states, paused states, and terminal states.

An application can easily determine the class of a specific state by performing Boolean bit operations with the RASCS_PAUSED and RASCS_DONE bitmasks. Here are some examples:

fDoneState = (state & RASCS_DONE);

fPausedState = (state & RASCS_PAUSED);

fRunState = !(fDoneState || fPausedState);

See Also

RasDial, RasGetConnectStatus, RasGetProjectionInfo, RASCONNSTATUS


RASPROJECTION

typedef enum _RASPROJECTION {

    RASP_Amb = 0x10000,

    RASP_PppNbf = 0x803F,

    RASP_PppIpx = 0x802B,

    RASP_PppIp = 0x8021

} RASPROJECTION ;

The RASPROJECTION enumeration type defines values that specify a particular authentication protocol or Point-to-Point Protocol control protocol (PPP). An application passes a value of this type to the RasGetProjectionInfo function to specify the protocol of interest.

Each of the RASPROJECTION enumerators has a corresponding data structure; the RasGetProjectionInfo function returns the specified information in a structure of that type.

Value	Meaning
RASP_Amb	Specifies the Authentication Message Block (AMB) authentication protocol. AMB is a NetBIOS-based protocol used to authenticate with downlevel remote access servers ( all those prior to Windows NT 3.5). The corresponding data structure is a RASAMB.
RASP_PppNbf	Specifies the NetBEUI Framer (NBF) protocol. NBFCP is a PPP network control protocol used to negotiate the parameters necessary to ship NetBEUI packets on a WAN link. The corresponding data structure is a RASPPPNBF.
RASP_PppIpx	Specifies the Internetwork Packet Exchange (IPX) control protocol. IPXCP is a PPP network control protocol used to negotiate the parameters necessary to ship IPX packets on a WAN link. The corresponding data structure is a RASPPPIPX.
RASP_PppIp	Specifies the Internet Protocol (IP) control protocol. IPCP is a PPP network control protocol used to negotiate the parameters necessary to ship IP packets on a WAN link.  The corresponding data structure is a RASPPPIP.
See Also

RasGetProjectionInfo, RASAMB, RASPPPIP, RASPPPIPX, RASPPPNBF


SECURITY_IMPERSONATION_LEVEL

typedef enum _SECURITY_IMPERSONATION_LEVEL { // sil

    SecurityAnonymous,

    SecurityIdentification,

    SecurityImpersonation,

    SecurityDelegation

} SECURITY_IMPERSONATION_LEVEL;

The SECURITY_IMPERSONATION_LEVEL enumeration type contains values that specify security impersonation levels. Security impersonation levels govern the degree to which a server process can act on behalf of a client process.

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

Impersonation is the ability of a process to take on the security attributes of another process.

See Also

CreatePrivateObjectSecurity, DuplicateToken, GetTokenInformation, ImpersonateSelf, OpenThreadToken


SID_NAME_USE

typedef enum _SID_NAME_USE {

    SidTypeUser = 1,

    SidTypeGroup,

    SidTypeDomain,

    SidTypeAlias,

    SidTypeWellKnownGroup,

    SidTypeDeletedAccount,

    SidTypeInvalid,

    SidTypeUnknown

} SID_NAME_USE;

The SID_NAME_USE enumeration type contains values that specify the type of a security identifier (SID).

Value	Meaning
SidTypeUser	Indicates a user SID.
SidTypeGroup	Indicates a group SID.
SidTypeDomain	Indicates a domain SID.
SidTypeAlias	Indicates an alias SID.
SidTypeWellKnownGroup	Indicates an SID for a well-known group.
SidTypeDeletedAccount	Indicates an SID for a deleted account.
SidTypeInvalid	Indicates an invalid SID.
SidTypeUnknown	Indicates an unknown SID type.
See Also

LookupAccountName, LookupAccountSid


TOKEN_INFORMATION_CLASS

typedef enum _TOKEN_INFORMATION_CLASS { // tic

    TokenUser = 1,

    TokenGroups,

    TokenPrivileges,

    TokenOwner,

    TokenPrimaryGroup,

    TokenDefaultDacl,

    TokenSource,

    TokenType,

    TokenImpersonationLevel,

    TokenStatistics

} TOKEN_INFORMATION_CLASS;

The TOKEN_INFORMATION_CLASS enumeration type contains values that specify the type of information being assigned to or retrieved from an access token.

See Also

GetTokenInformation, SetTokenInformation, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_TYPE

typedef enum tagTOKEN_TYPE { // tt

    TokenPrimary = 1,

    TokenImpersonation

} TOKEN_TYPE;

The TOKEN_TYPE enumeration type contains values that differentiate between a primary token and an 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


_hread

The _hread function reads data from the specified file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the ReadFile function.

long _hread(

HFILE  hFile,	// handle of file
LPVOID  lpBuffer,	// address of buffer for read data
long  lBytes	// length, in bytes, of data buffer
);
Parameters

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 be read from the file.

Return Value

The return value indicates the number of bytes actually read from the file. If the number of bytes read is less than lBytes, the function has reached the end of file (EOF) before reading the specified number of bytes.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

_hwrite, ReadFile


_hwrite

The _hwrite function writes data to the specified file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the WriteFile function.

long _hwrite(

HFILE  hFile,	// handle of file
LPCSTR  lpBuffer,	// address of buffer for data to be written
long  lBytes	// number of bytes to write
);
Parameters

hFile

Identifies the specified file.

lpBuffer

Points to a buffer that contains the data to be written to the file.

lBytes

Specifies the number of bytes to be written to the file.

Return Value

If the function succeeds, the return value indicates the number of bytes actually written to the file.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

_hread, WriteFile


_lclose

The _lclose function closes the specified file so that it is no longer available for reading or writing. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the CloseHandle function.

HFILE _lclose(

HFILE  hFile	// handle of file to close
);
Parameters

hFile

Identifies the file to be closed. This handle is returned by the function that created or last opened the file.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

CloseHandle, CreateFile, _lopen


_lcreat

The _lcreat function creates or opens a specified file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the CreateFile function.

HFILE _lcreat(

LPCSTR  lpPathName,	// address of name of file to open
int  iAttribute	// file attribute
);
Parameters

lpPathName

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.

iAttribute

Specifies the file attributes. This parameter must be one of the following values:

Value	Meaning
0	Normal (can be read from or written to without restriction).
1	Read only (cannot be opened for write)
2	Hidden (not found by directory search)
4	System (not found by directory search)
Return Value

If the function succeeds, the return value is a file handle.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

Remarks

If the file does not exist, _lcreat creates a new file and opens it for writing. If the file exists, _lcreat truncates the file size to zero and opens it for reading and writing. When the function opens the file, the pointer is set to the beginning of the file.

The _lcreat function should be used carefully. It can open any file, even one already opened by another function.

See Also

CreateFile, _lopen


_llseek

The _llseek function repositions the file pointer in a previously opened file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the SetFilePointer function.

LONG _llseek(

HFILE  hFile,	// handle of file
LONG  lOffset,	// number of bytes to move
int  iOrigin	// position to move from
);
Parameters

hFile

Identifies the file.

lOffset

Specifies the number of bytes the file pointer is to be moved.

iOrigin

Specifies the starting position and direction of the file pointer. This parameter must be one of the following values:

Value	Meaning
FILE_BEGIN	Moves the file pointer lOffset bytes from the beginning of the file.
FILE_CURRENT	Moves the file pointer lOffset bytes from its current position.
FILE_END	Moves the file pointer lOffset bytes from the end of the file.
Return Value

If the function succeeds, the return value specifies the new offset of the pointer, in bytes, from the beginning of the file.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

Remarks

When a file is initially opened, the file pointer is set to the beginning of the file. The _llseek function moves the pointer an arbitrary amount without reading data, which facilitates random access to the file's contents.

See Also

_lopen, SetFilePointer


_lopen

The _lopen function opens an existing file and sets the file pointer to the beginning of the file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the CreateFile function.

HFILE _lopen(

LPCSTR  lpPathName,	// address of name of file to open
int  iReadWrite	// file access mode
);
Parameters

lpPathName

Points to a null-terminated string that names the file to open. The string must consist of characters from the Windows ANSI character set.

iReadWrite

Specifies the modes in which to open the file. This parameter consists of one access mode and an optional share mode. The access mode must be one of the following values:

Value	Meaning
OF_READ	Opens the file for reading only.
OF_READWRITE	Opens the file for reading and writing.
OF_WRITE	Opens the file for writing only.
The share mode can be one of the following values:

Value	Meaning
OF_SHARE_COMPAT	Opens the file in compatibility mode, enabling any process on a given computer to open the file any number of times. If the file has been opened by using any of the other share modes, _lopen fails.
OF_SHARE_DENY_NONE	Opens the file without denying other processes read or write access to the file. If the file has been opened in compatibility mode by any other process, _lopen fails.
OF_SHARE_DENY_READ	Opens the file and denies other processes read access to the file. If the file has been opened in compatibility mode or for read access by any other process, _lopen fails.
OF_SHARE_DENY_WRITE	Opens the file and denies other processes write access to the file. If the file has been opened in compatibility mode or for write access by any other process, _lopen fails.
OF_SHARE_EXCLUSIVE	Opens the file in exclusive mode, denying other processes both read and write access to the file. If the file has been opened in any other mode for read or write access, even by the current process, _lopen fails.
Return Value

If the function succeeds, the return value is a file handle.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

CreateFile


_lread

The _lread function reads data from the specified file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the ReadFile function.

UINT _lread(

HFILE  hFile,	// handle of file
LPVOID  lpBuffer,	// address of buffer for read data
UINT  uBytes	// length, in bytes, of data buffer
);
Parameters

hFile

Identifies the specified file.

lpBuffer

Points to a buffer that contains the data read from the file.

uBytes

Specifies the number of bytes to be read from the file.

Return Value

The return value indicates the number of bytes actually read from the file. If the number of bytes read is less than uBytes, the function has reached the end of file (EOF) before reading the specified number of bytes.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

_lwrite, ReadFile


_lwrite

The _lwrite function writes data to the specified file. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the WriteFile function.

UINT _lwrite(

HFILE  hFile,	// handle of file
LPCSTR  lpBuffer,	// address of buffer for data to be written
UINT  uBytes	// number of bytes to write
);
Parameters

hFile

Identifies the specified file.

lpBuffer

Points to a buffer that contains the data to write to the file.

uBytes

Specifies the number of bytes to be written to the file.

Return Value

If the function succeeds, the return value indicates the number of bytes actually written to the file.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

See Also

_lread, WriteFile


AbnormalTermination

The AbnormalTermination function indicates whether the try block of a try-finally statement terminated normally. The function can be called only from within the finally block of a try-finally statement.

BOOL AbnormalTermination(VOID)

Parameters

This function has no parameters.

Return Value

If the try block of the try-finally statement terminated abnormally, the return value is TRUE; otherwise, it is FALSE.

Remarks

The try block terminates normally only if execution leaves the block sequentially after executing the last statement in the block. Statements (such as return, goto, continue, or break) that cause execution to leave the try block result in abnormal termination of the block. This is the case even if such a statement is the last statement in the try block.

Abnormal termination of a try block causes the system to search backward through all stack frames to determine whether any termination handlers must be called. This can result in the execution of hundreds of instructions, so it is important to avoid abnormal termination of a try block due to a return, goto, continue, or break statement. Note that these statements do not generate an exception, even though the termination is abnormal.


AbortDoc

The AbortDoc function stops the current print job and erases everything drawn since the last call to the StartDoc function. This function replaces the ABORTDOC printer escape.

int AbortDoc(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context for the print job.

Return Value

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is SP_ERROR. To get extended error information, call GetLastError.

Remarks

Applications should call the AbortDoc function to stop a print job if an error occurs, or to stop a print job after the user cancels that job. To end a successful print job, an application should call the EndDoc function.

If Windows Print Manager was used to start the print job, calling 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

The AbortPath function closes and discards any paths in the specified device context.

BOOL AbortPath(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context from which a path will be discarded.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If there is an open path bracket in the given device context, the path bracket is closed and the path is discarded. If there is a closed path in the device context, the path is discarded.

See Also

BeginPath, EndPath


AbortPrinter

The AbortPrinter function deletes a printer's spool file if the printer is configured for spooling.

BOOL AbortPrinter(

HANDLE  hPrinter	// handle of printer object
);
Parameters

hPrinter

Identifies the printer from which the spool file is deleted.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the printer is not configured for spooling, AbortPrinter has no effect.

The printer handle identified by the hPrinter parameter is returned by the OpenPrinter function.

See Also

OpenPrinter


AbortProc

The AbortProc function is an application-defined callback function that is called when a print job is to be canceled during spooling.

BOOL CALLBACK AbortProc(

HDC  hdc,	// handle of device context
int  iError	// error value
);
Parameters

hdc

Identifies the device context for the print job.

iError

Specifies whether an error has occurred. This parameter is zero if no error has occurred; it is SP_OUTOFDISK if Windows Print Manager is currently out of disk space and more disk space will become available if the application waits.

Return Value

The callback function should return TRUE to continue the print job or FALSE to cancel the print job.

Remarks

An application installs this callback function by calling the SetAbortProc function. 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


AbortSystemShutdown

The AbortSystemShutdown function stops a system shutdown started by using the InitiateSystemShutdown function.

BOOL AbortSystemShutdown(

LPTSTR  lpMachineName	// address of name of computer to stop shutting down
);
Parameters

lpMachineName

Points to the null-terminated string that specifies the network name of the computer where the shutdown is to be stopped. If lpMachineName is NULL or points to an empty string, the function stops the shutdown on the local computer.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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


accept

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

SOCKET accept (

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

s

A descriptor identifying a socket that is in listen mode.

addr

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

addrlen

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

Return Value

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

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

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEFAULT	The addrlen argument is too small (less than the size of a sockets address structure).
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets call is in progress.
WSAEINVAL	The listen function was not invoked before accept.
WSAEMFILE	The queue is empty upon entry to accept and there are no descriptors available.
WSAENOBUFS	No buffer space is available.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	The referenced socket is not a type that supports connection-oriented service.
WSAEWOULDBLOCK	The socket is marked as nonblocking and no connections are present to be accepted.
Remarks

This function extracts the first connection on the queue of pending connections on s, creates a new socket with the same properties as s and returns a handle to the new socket. If no pending connections are present on the queue, and the socket is not marked as nonblocking, accept blocks the caller until a connection is present. If the socket is marked nonblocking and no pending connections are present on the queue, accept returns an error as described following. The accepted socket may not be used to accept more connections. The original socket remains open.

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

See Also

bind, connect, listen, select, socket, WSAAsyncSelect, WSACancelBlockingCall, WSAStartup


AccessCheck

The AccessCheck function is used by a server application to check a client's access to an object against the access control associated with the object.

BOOL AccessCheck(

PSECURITY_DESCRIPTOR  pSecurityDescriptor,	// address of security descriptor
HANDLE  ClientToken,	// handle of client access token
DWORD  DesiredAccess,	// access mask to request
PGENERIC_MAPPING  GenericMapping,	// address of generic-mapping structure
PPRIVILEGE_SET  PrivilegeSet,	// address of privilege-set structure
LPDWORD  PrivilegeSetLength,	// size of privilege-set structure
LPDWORD  GrantedAccess,	// address of granted access mask
LPBOOL  AccessStatus	// address of flag indicating whether access granted
);
Parameters

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure against which access is checked.

ClientToken

Identifies an access token representing a client attempting to gain access.

This handle must be obtained from a communications session layer — for instance, a named pipe — to prevent possible security policy violations.

DesiredAccess

Specifies the access mask to be requested. This mask must have been mapped by the MapGenericMask function to contain no generic access rights.

GenericMapping

Points to the GENERIC_MAPPING structure associated with the object for which access is being checked.

PrivilegeSet

Points to a PRIVILEGE_SET structure that the function fills with any privileges used to perform the access validation. If no privileges were used, the buffer contains a privilege set consisting of zero privileges.

PrivilegeSetLength

Specifies the size, in bytes, of the buffer pointed to by the PrivilegeSet parameter.

GrantedAccess

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.

AccessStatus

Points to a flag indicating the success or failure of the access check. If AccessStatus is TRUE, the access token has the requested access to the object. If AccessStatus is FALSE, the access token does not have the requested access. When this parameter is FALSE, the application can use the GetLastError function to get extended error information.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The AccessCheck function compares the specified security descriptor with the specified access token and indicates, in the AccessStatus parameter, whether access is granted or denied. If access is granted, the requested access mask becomes the object's granted access mask.

Only the discretionary access-control list is examined during an access check.

See Also

AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, GENERIC_MAPPING, MapGenericMask, PrivilegeCheck, PRIVILEGE_SET, SECURITY_DESCRIPTOR


AccessCheckAndAuditAlarm

The AccessCheckAndAuditAlarm function performs an access validation and generates corresponding audit messages. An application can also use this function to determine whether necessary privileges are held by a client process. This function is generally used by a server application impersonating a client process. Alarms are not supported in the current version of Windows NT.

BOOL AccessCheckAndAuditAlarm(

LPCTSTR  SubsystemName,	// address of string for subsystem name
LPVOID  HandleId,	// address of handle identifier
LPTSTR  ObjectTypeName,	// address of string for object type
LPTSTR  ObjectName,	// address of string for object name
PSECURITY_DESCRIPTOR  SecurityDescriptor,	// address of security descriptor
DWORD  DesiredAccess,	// mask for requested access rights
PGENERIC_MAPPING  GenericMapping,	// address of GENERIC_MAPPING
BOOL  ObjectCreation,	// object-creation flag
LPDWORD  GrantedAccess,	// address of mask for granted rights
LPBOOL  AccessStatus,	// address of flag for results
LPBOOL  pfGenerateOnClose	// address of flag for audit generation
);
Parameters

SubsystemName

Points to a null-terminated string specifying the name of the subsystem calling the function — for example, "DEBUG" or "WIN32."

HandleId

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.

ObjectTypeName

Points to a null-terminated string specifying the type of object being created or accessed. This string appears in the audit log for the object.

ObjectName

Points to a null-terminated string specifying the name of the object being created or accessed. This string appears in the audit log for the object.

SecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure against which access is checked.

DesiredAccess

Specifies an access mask giving the requested access rights. This mask must have been mapped to contain no generic access rights by the MapGenericMask function.

GenericMapping

Points to the GENERIC_MAPPING structure associated with the type of object being examined.

ObjectCreation

Specifies a flag that determines whether the calling application will create a new object when access is granted. If this flag is TRUE, the application creates a new object; if it is FALSE, the application opens an existing object.

GrantedAccess

Points to a buffer that receives an access mask indicating which access rights were granted, if the function succeeds.

AccessStatus

Points to a flag that the function sets to indicate the success or failure of the access check. If access is granted, this flag is TRUE; otherwise, it is FALSE.

pfGenerateOnClose

Points to a flag set by the audit-generation routine when the function returns. This flag must be passed to the ObjectCloseAuditAlarm function when the object handle is closed.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The AccessCheckAndAuditAlarm function compares the specified security descriptor with the impersonation access token of the calling process and indicates whether access is granted or denied. If access is granted, the requested access mask becomes the granted access mask for the object. This function also generates any necessary audit messages as a result of the access attempt.

This function requires the calling process to have the SE_AUDIT_NAME privilege. The test for this privilege is performed against the primary token of the calling process, not the impersonation token of the thread.

See Also

AccessCheck, AreAllAccessesGranted, AreAnyAccessesGranted, GENERIC_MAPPING, MapGenericMask, ObjectCloseAuditAlarm, ObjectOpenAuditAlarm, ObjectPrivilegeAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm, SECURITY_DESCRIPTOR


AccessResource

The AccessResource function is not implemented in the Win32 API. Win32-based applications should use the LoadResource, LockResource, and FindResource functions.


AcsLan

The AcsLan function is used to communicate with other computers or network peripheral devices, such as printers, using the data link control (DLC) protocol. The caller submits requests by filling in a command control block (CCB) and then calling AcsLan.

Commands submitted through AcsLan can complete synchronously or asynchronously. The DLC driver, not the caller, determines how a command completes. This is unlike the Netbios function, for example, which has commands complete synchronously or asynchronously as requested by the caller.

There are some differences between NT DLC and the CCB2 interface. The most notable difference is that the buffer pool must be specified on an open adapter instance basis and not specified per-SAP (service-access point). After an adapter has been opened using the DIR.OPEN.ADAPTER command, a buffer pool must be given to the DLC driver using BUFFER.CREATE.

ACSLAN_STATUS AcsLan(

PLLC_CCB  pCcb,	// address of command control block
PLLC_CCB * ppBadCcb	// address of pointer for invalid CCB
);
Parameters

pCcb

Points to an LLC_CCB structure describing the function being performed. For information about this structure, see documentation for IBM LAN.

ppBadCcb

Points to a pointer to an LLC_CCB structure. This parameter is used when a chain of LLC_CCB structures is submitted. If the parameter is not NULL on input, this pointer will contain a pointer to the first invalid LLC_CCB structure discovered in the chain.

Return Value

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

Value	Meaning
ACSLAN_STATUS_COMMAND_ACCEPTED	The request has been processed and passed to the DLC driver. The command may or may not have already completed, depending on whether it is a synchronous or asynchronous command and depending on other timing considerations. This value does not mean that the command completed successfully. The caller must check the uchDlcStatus member in the LLC_CCB structure to determine whether the request succeeded or failed.
ACSLAN_STATUS_INVALID_CCB_POINTER	A pointer in the the LLC_CCB structure, or the parameter table is invalid.
ACSLAN_STATUS_CCB_IN_ERROR	A problem was detected with the LLC_CCB structure. The caller should check the values in the structure and resubmit it.
ACSLAN_STATUS_CHAINED_CCB_IN_ERROR	A problem was detected with an LLC_CCB structure in a chain of LLC_CCB structures.
ACSLAN_STATUS_SYSTEM_ERROR	This value is not used.
ACSLAN_STATUS_SYSTEM_STATUS	This value is not used.
ACSLAN_STATUS_INVALID_COMMAND	The command in the uchDlcCommand member of the LLC_CCB structure is unrecognized.
See Also

Netbios


ActivateKeyboardLayout

The implementations of ActivateKeyboardLayout in Windows 95 and Windows NT are substantially different. To accommodate these differences, this reference page first presents the Windows 95 implementation in its entirety, followed by the Windows NT version.

Windows 95:

The ActivateKeyboardLayout function sets the input language for the current thread. This function accepts a keyboard layout handle that identifies a locale as well as the physical layout of the keyboard.

HKL ActivateKeyboardLayout(

HKL  hkl,	// handle of keyboard layout
UINT  Flags	// keyboard layout flags
);
Parameters

hkl

Handle of a keyboard layout or a zero-extended locale identifier. This parameter can be any valid keyboard layout handle obtained using the LoadKeyboardLayout or GetKeyboardLayoutList function or one of the following values:

Value	Meaning
HKL_NEXT	Selects the next layout in the keyboard layouts list maintained by the system.
HKL_PREV	Selects the previous layout in the keyboards layout list maintained by the system.
Flags

Specifies the keyboard layout flags. The value of this parameter can be:

Value	Meaning
KLF_REORDER	Reorders the keyboard layouts list by moving the given keyboard layout handle to the head of the list. If this value is not given, the list is rotated without a change of order. For example, if a user had an English layout active, as well as having French, German and Spanish layouts loaded (in that order), then activating the German layout with the KLF_REORDER bit set would produce the following order: German, English, French, Spanish. Activating the German layout without the KLF_REORDER value set would produce the following order: German, Spanish, English, French.
Return Value

If the function succeeds, the return value is the return value is the previous keyboard layout handle. Otherwise, it is zero. To get extended error information, use the GetLastError function.

Remarks

Several keyboard layouts can be loaded at any one time, but only one is active at a time. Loading multiple keyboard layouts makes it possible to rapidly switch between layouts.

An application can create a valid keyboard layout handle by setting the high word to zero and the low word to a locale identifier. Using such keyboard layout handles changes the input language without affecting the physical layout.

When multiple input method editors (IMEs) are allowed for each locale, passing in a keyboard layout handle in which the high word (the device handle) is zero activates the first IME in the list "belonging" to the locale.

See Also

LoadKeyboardLayout, GetKeyboardLayoutName, UnloadKeyboardLayout

Windows NT:

The ActivateKeyboardLayout function activates a different keyboard layout.

BOOL ActivateKeyboardLayout(

HKL  hkl,	// handle of keyboard layout
UINT  Flags	// keyboard layout flags
);
Parameters

hkl

Identifies the keyboard layout to be activated. The layout must have been loaded by a previous call to the LoadKeyboardLayout function. This parameter must be either the handle 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_PREV	Selects the previous layout in the circular list of loaded layouts maintained by the system.
Flags

Specifies how the keyboard layout is to be activated. This parameter can be one of the following values:

Value	Meaning
KLF_REORDER	If this bit is set, the system's circular list of loaded keyboard layouts is reordered. If this bit is not set, the list is rotated without a change of order. For example, if a user had an English layout active, as well as having French, German and Spanish layouts loaded (in that order), then activating the German layout with the KLF_REORDER bit set would produce the following order: German, English, French, Spanish. Activating the German layout without the KLF_REORDER bit set would produce the following order: German, Spanish, English, French. If less than three keyboard layouts are loaded, the value of this flag is irrelevant.
KLF_UNLOADPREVIOUS	The previously active layout is unloaded.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Several keyboard layouts can be loaded at any one time, but only one is active at a time. Loading multiple keyboard layouts makes it possible to rapidly switch between layouts.

See Also

LoadKeyboardLayout, GetKeyboardLayoutName, UnloadKeyboardLayout


AddAccessAllowedAce

The AddAccessAllowedAce function adds an access-allowed ACE to an ACL. The access is granted to a specified SID.

An ACE is an access-control entry. An ACL is an access-control list. A SID is a security identifier.

BOOL AddAccessAllowedAce(

PACL  pAcl,	// address of access-control list
DWORD  dwAceRevision,	// ACL revision level
DWORD  AccessMask,	// access mask
PSID  pSid	// address of security identifier
);
Parameters

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.

dwAceRevision

Specifies the revision level of the ACL being modified. Currently, this value must be ACL_REVISION.

AccessMask

Specifies the mask of access rights to be granted to the specified SID.

pSid

Points to the SID structure representing a process being granted access.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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

ACCESS_ALLOWED_ACE, ACE_HEADER, ACL, AddAccessDeniedAce, AddAce, AddAuditAccessAce, DeleteAce, GetAce


AddAccessDeniedAce

The AddAccessDeniedAce function adds an access-denied ACE to an ACL. The access is denied to a specified SID.

An ACE is an access-control entry. An ACL is an access-control list. A SID is a security identifier.

BOOL AddAccessDeniedAce(

PACL  pAcl,	// address of access-control list
DWORD  dwAceRevision,	// ACL revision level
DWORD  AccessMask,	// access mask
PSID  pSid	// address of security identifier
);
Parameters

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.

dwAceRevision

Specifies the revision level of the ACL being modified. Currently, this value must be ACL_REVISION.

AccessMask

Specifies the mask of access rights being denied to the specified SID.

pSid

Points to the SID structure representing the process being denied access.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The ACE_HEADER structure placed in the ACE by this function specifies a type and size, but provides no ACE flags.

See Also

ACCESS_DENIED_ACE, ACE_HEADER, ACL, AddAccessAllowedAce, AddAce, AddAuditAccessAce, DeleteAce, GetAce


AddAce

The AddAce function adds one or more ACEs to a specified ACL.

An ACE is an access-control entry. An ACL is an access-control list.

BOOL AddAce(

PACL  pAcl,	// address of access-control list
DWORD  dwAceRevision,	// ACL revision level
DWORD  dwStartingAceIndex,	// index of ACE position in ACL
LPVOID  pAceList,	// address of one or more ACEs
DWORD  nAceListLength	// size of buffer for ACEs
);
Parameters

pAcl

Points to an ACL structure. This function adds an ACE to this ACL.

dwAceRevision

Specifies the revision level of the ACL being modified. Currently, this value must be ACL_REVISION.

dwStartingAceIndex

Specifies the position in the ACL's list of ACEs at which to add new ACEs. A value of zero inserts the ACEs at the beginning of the list. A value of MAXDWORD appends the ACEs to the end of the list.

pAceList

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.

nAceListLength

Specifies the size, in bytes, of the input buffer pointed to by the pAceList parameter.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Applications frequently use the FindFirstFreeAce and GetAce functions when using the AddAce function to manipulate an ACL. In addition, the ACL_SIZE_INFORMATION structure retrieved by the GetAclInformation function contains the size of the ACL and the number of ACEs it contains.

See Also

ACL, ACL_SIZE_INFORMATION, AddAccessAllowedAce, AddAccessDeniedAce, AddAuditAccessAce, DeleteAce, FindFirstFreeAce, GetAce, GetAclInformation


AddAtom

The AddAtom function adds a character string to the local atom table and returns a unique value (an atom) identifying the string.

ATOM AddAtom(

LPCTSTR  lpString	// address of string to add
);
Parameters

lpString

Points to the null-terminated string to be added. The string can have a maximum size of 255 bytes. Strings differing only in case are considered identical. The case of the first string added is preserved and returned by the GetAtomName function.

Return Value

If the function succeeds, the return value is the newly created atom.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The AddAtom function stores no more than one copy of a given string in the atom table. If the string is already in the table, the function returns the existing atom and, in the case of a string atom, increments the string's reference count.

The MAKEINTATOM macro can be used to convert a WORD value into a string that can be added to the atom table by using the AddAtom function.

AddAtom returns a string atom whose value is in the range 0xC000 through 0xFFFF.

If lpString has the form "#1234", AddAtom returns an integer atom whose value is the 16-bit representation of the decimal number specified in the string (0x04D2, in this example). If the decimal value specified is 0x0000 or a value in the range 0xC000 through 0xFFFF, the return value is zero, indicating an error. If lpString is in the range 0x0001 through 0xBFFF, the return value is the low-order word of lpString.

See Also

DeleteAtom, FindAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName, MAKEINTATOM


AddAuditAccessAce

The AddAuditAccessAce function adds a system-audit ACE to a system ACL. The access of a specified SID is audited.

An ACE is an access-control entry. An ACL is an access-control list. A SID is a security identifier.

BOOL AddAuditAccessAce(

PACL  pAcl,	// address of access-control list
DWORD  dwAceRevision,	// ACL revision level
DWORD  dwAccessMask,	// access mask
PSID  pSid,	// address of security identifier
BOOL  bAuditSuccess,	// flag for auditing successful access
BOOL  bAuditFailure	// flag for auditing unsuccessful access attempts
);
Parameters

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.

dwAceRevision

Specifies the revision level of the ACL being modified. Currently, this value must be ACL_REVISION.

dwAccessMask

Specifies the mask of access rights to be audited for the specified SID.

pSid

Points to the SID structure representing the process whose access is being audited.

bAuditSuccess

Specifies whether successful access attempts are to be audited. Set this flag to TRUE to enable auditing; otherwise, set it to FALSE.

bAuditFailure

Specifies whether unsuccessful access attempts are to be audited. Set this flag to TRUE to enable auditing; otherwise, set it to FALSE.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The ACE_HEADER structure placed in the ACE by this function specifies a type and size, but provides no ACE flags.

See Also

ACE_HEADER, ACL, AddAccessAllowedAce, AddAccessDeniedAce, AddAce, DeleteAce, GetAce, SID, SYSTEM_AUDIT_ACE


AddFontResource

The AddFontResource function adds the font resource from the specified file to the Windows font table. The font can subsequently be used for text output by any Windows-based application.

int AddFontResource(

LPCTSTR  lpszFilename	// address of font-resource filename
);
Parameters

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.

Return Value

If the function succeeds, the return value specifies the number of fonts added.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Any application that adds or removes fonts from the Windows font table should notify other windows of the change by sending a WM_FONTCHANGE message to all top-level windows in the operating system. The application should send this message by calling the SendMessage function and setting the hwnd parameter to HWND_BROADCAST.

When an application no longer needs a font resource that it loaded by calling the AddFontResource function, it must remove the resource by calling the RemoveFontResource function.

See Also

RemoveFontResource, SendMessage


AddForm
AddForm  (preliminary−Windows NT)

The AddForm function adds a form to the list of available forms that can be selected for the specified printer.

BOOL AddForm(

HANDLE  hPrinter,	// handle of printer object
DWORD  Level,	// data-structure level
LPBYTE  pForm	// address of form info. data structure
);
Parameters

hPrinter

Identifies the printer that supports printing with the specified form.

Level

Specifies the level of the structure to which pForm points. This value must be 1.

pForm

Points to a FORM_INFO_1 structure.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The printer handle identified by the hPrinter parameter is returned by the OpenPrinter function.

An application can determine which forms are available for a printer by calling the EnumForms function.

See Also

EnumForms, FORM_INFO_1, OpenPrinter


AddJob

The AddJob function obtains a path string that specifies a file that you can use to store a spooled print job.

BOOL AddJob(

HANDLE  hPrinter,	// specifies printer for the print job
DWORD  Level,	// specifies version of print job information data structure
LPBYTE  pData,	// points to buffer to receive print job information data
DWORD  cbBuf,	// specifies size of buffer pointed to by pData
LPDWORD  pcbNeeded	// points to variable to receive size of print job information data
);
Parameters

hPrinter

Handle that specifies the printer for the print job. This must be a local printer that is configured as a spooled printer. If hPrinter is a handle to a remote printer connection, or if the printer is configured for direct printing, the AddJob function fails.

Level

Specifies the version of the print job information data structure that the function stores into the buffer pointed to by pData. Set this parameter to one.

pData

Points to a buffer to receive an ADDJOB_INFO_1 data structure and a path string.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pData. The buffer needs to be large enough to contain an ADDJOB_INFO_1 structure and a path string.

pcbNeeded

Points to a variable to receive the total size, in bytes, of the ADDJOB_INFO_1 data structure plus the path string. If this value is less than or equal to cbBuf and the function succeeds, this is the actual number of bytes written to the buffer pointed to by pData. If this number is greater than cbBuf, the buffer is too small, and you must call the function again with a buffer size at least as large as *pcbNeeded.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

You can call the CreateFile function to open the spool file specified by the Path member of the ADDJOB_INFO_1 structure, and then call the WriteFile function to write print job data to it. Once that is done, call ScheduleJob to notify the print spooler that the print job can now be scheduled by the spooler for printing.

See Also

ADDJOB_INFO_1, CreateFile, OpenPrinter, ScheduleJob, WriteFile


AddMonitor

The AddMonitor function installs a local printer monitor and links the configuration, data, and monitor files. Future releases of Windows NT may allow remote installation of printer monitors.

BOOL AddMonitor (

LPTSTR  pName,	// address of server name
DWORD  Level,	// monitor info. structure level
LPBYTE  pMonitors	// address of monitor info structure
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Before an application calls AddMonitor, all files required by the monitor must be copied to the SYSTEM32 directory.

An application can determine which printer monitors are currently installed by calling the EnumMonitors function.

A monitor added by AddMonitor may be removed by calling DeleteMonitor.

See Also

DeleteMonitor, EnumMonitors, MONITOR_INFO_2


AddPort

The AddPort function adds the name of a port to the list of supported ports.

BOOL AddPort(

LPTSTR  pName,	// address of a server name
HWND  hWnd,	// handle of parent window
LPTSTR  pMonitorName	// address of a monitor name
);
Parameters

pName

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.

pMonitorName

Points to a null-terminated string that specifies the monitor associated with the port.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The monitor name specified in pMonitorName 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

The AddPrinter function adds a printer to the list of supported printers for a specified server.

HANDLE AddPrinter(

LPTSTR  pName,	// address of server name
DWORD  Level,	// printer info. structure level
LPBYTE  pPrinter	// address of structure
);
Parameters

pName

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.

Level

Specifies the version of the structure to which pPrinter points. This value must be 2.

pPrinter

Points to a PRINTER_INFO_2 structure that contains information about the printer. You must set the pPrinterName, pPortName, pDriverName, pPrintProcessor, and pDatatype members of this structure before calling AddPrinter.

Return Value

If the function succeeds, the return value is the handle of a new printer object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The following list identifies the members of the PRINTER_INFO_2 structure that can be set before this function is called.

Attributes	pPrintProcessor
DefaultPriority	Priority
pComment	pSecurityDescriptor
pDatatype	pSepFile
pDevMode	pShareName
pLocation	StartTime
pParameters	UntilTime
The Status, cJobs, and AveragePPM members of the PRINTER_INFO_2 structure are reserved for use by the GetPrinter function. They must not be set before calling AddPrinter.

If pSecurityDescriptor is NULL, the system assigns a default security descriptor to the printer.

After an application creates a printer object with the AddPrinter function, it must use the PrinterProperties function to specify the correct settings for the printer driver associated with the printer object.

The AddPrinter function returns an error if a printer object with the same name already exists, unless that object is marked as pending deletion. In that case, the existing printer will not be deleted, and the AddPrinter creation parameters will be used to change the existing printer settings (as if the application had used the SetPrinter function).

Windows NT:The caller of the AddPrinter function must have SERVER_ACCESS_ADMINISTER access to the server on which the printer is to be created. The handle returned by the function will have PRINTER_ALL_ACCESS permission, and can be used to perform administrative operations on the printer.

Windows 95: This access validation is not supported in Windows 95.

Use the EnumPrintProcessors function to enumerate the set of print processors installed on a server. Use the EnumPrintProcessorDatatypes function to enumerate the set of datatypes that a print processor supports.

See Also

DeletePrinter, EnumPrintProcessors, EnumPrintProcessorDatatypes, GetPrinter, PRINTER_INFO_2, PrinterProperties, SetPrinter


AddPrinterConnection
AddPrinterConnection  (preliminary−Windows NT)

The AddPrinterConnection function adds a connection to the specified printer for the current user.

BOOL AddPrinterConnection (

LPTSTR  pName	// address of printer name
);
Parameters

pName

Points to a null-terminated string that specifies the name of a printer that the current user wishes to establish a connection to.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

When Windows NT makes a connection to a printer, it may need to copy printer driver files to the workstation. If the user does not have permission to copy files to the appropriate location, the AddPrinterConnection function fails, and GetLastError returns ERROR_ACCESS_DENIED.

A printer connection established by calling AddPrinterConnection will be enumerated when EnumPrinters is called with dwType set to PRINTER_ENUM_CONNECTION.

See Also

ConnectToPrinterDlg, DeletePrinterConnection, EnumPrinters


AddPrinterDriver

The AddPrinterDriver function installs a local or remote printer driver and links the configuration, data, and driver files.

BOOL AddPrinterDriver(

LPTSTR  pName,	// address of server name
DWORD  Level,	// printer info. structure level
LPBYTE  pDriverInfo	// address of printer info. structure
);
Parameters

pName

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.

Level

Specifies the version of the structure to which pDriverInfo points.

Windows 95: This value can be either 2 or 3.

Windows NT: This value must be 2.

pDriverInfo

Points to either a DRIVER_INFO_2 structure or a DRIVER_INFO_3 structure. If dwlevel is 2, this parameter receives a DRIVER_INFO_2 structure. If dwlevel is 3, this parameter receives a DRIVER_INFO_3 structure.

If the pEnvironment member of the structure pointed to by pDriverInfo is NULL, the current environment of the caller/client (not of the destination/server) is used.

Windows 95: This structure can be either DRIVER_INFO_2 or DRIVER_INFO_3.

Windows NT: This structure must be DRIVER_INFO_2.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Before an application calls AddPrinterDriver, all files required by the driver must be copied to the system's printer-driver directory. An application can retrieve the name of this directory by calling the GetPrinterDriverDirectory function.

An application can determine which printer drivers are currently installed by calling the EnumPrinterDrivers function.

See Also

DRIVER_INFO_2, EnumPrinterDrivers, GetPrinterDriverDirectory


AddPrintProcessor

The AddPrintProcessor function installs a print processor on the specified server and adds the print-processor name to an internal list of supported print processors.

BOOL AddPrintProcessor(

LPTSTR  pName,	// address of server name
LPTSTR  pEnvironment,	// address of environment name
LPTSTR  pPathName,	// address of path
LPTSTR  pPrintProcessorName	// address of print-processor name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the print processor should be installed. If this parameter is NULL, the print processor is installed locally.

pEnvironment

Points to a null-terminated string that specifies the environment. For example, "Windows x86" specifies Windows running on an Intel 80386 or 80486 processor. If this parameter is NULL, the current environment of the caller/client (not of the destination/server) is used.

pPathName

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.

pPrintProcessorName

Points to a null-terminated string that specifies the name of the print processor.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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

The AddPrintProvidor function installs a local printer provider and links the configuration, data, and provider files. Future releases of Windows may allow remote installation of printer providers.

BOOL AddPrintProvidor (

LPTSTR  pName,	// address of server name
DWORD  Level,	// provider information structure level
LPBYTE  pProvidorInfo	// address of provider information structure
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the provider should be installed. For this release of Windows 95 and Windows NT, providers may only be installed locally, so this parameter should be NULL.

Level

Specifies the level of the structure to which pProvidorInfo points. This value must be 1.

pProvidorInfo

Points to a PROVIDOR_INFO_1 structure.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Before an application calls this function, all files required by the provider must be copied to the SYSTEM32 directory.

A provider added by AddPrintProvidor may be removed by calling DeletePrintProvidor.

See Also

DeletePrintProvidor, PROVIDOR_INFO_1


AddPropSheetPageProc  (preliminaryWindows NT)
AddPropSheetPageProc  (preliminary−Windows NT)

The AddPropSheetPageProc function specifies an application-defined callback function that a property sheet extension uses to add a page to a property sheet.

BOOL CALLBACK AddPropSheetPageProc(

HPROPSHEETPAGE  hpage,
LPARAM  lParam
);
Parameters

hpage

Handle to a property sheet page.

lParam

Application-defined 32-bit value.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


AdjustTokenGroups

The AdjustTokenGroups function adjusts groups in the specified access token. TOKEN_ADJUST_GROUPS access is required to enable or disable groups in an access token.

BOOL AdjustTokenGroups(

HANDLE  TokenHandle,	// handle of token that contains groups
BOOL  ResetToDefault,	// flag for default settings
PTOKEN_GROUPS  NewState,	// address of new group information
DWORD  BufferLength,	// size of buffer for previous information
PTOKEN_GROUPS  PreviousState,	// address of previous group information
PDWORD  ReturnLength	// address of required buffer size
);
Parameters

TokenHandle

Identifies the access token containing the groups to be modified.

ResetToDefault

Specifies whether the groups are to be set to their default enabled and disabled states. If this value is TRUE, the groups are set to their default states and the NewState parameter is ignored. If this value is FALSE, the groups are set according to the information pointed to by the NewState parameter.

NewState

Points to a TOKEN_GROUPS structure containing the groups whose states are to be set. If the ResetToDefault parameter is FALSE, the function sets each of the groups to the value of that group's SE_GROUP_ENABLED flag in the TOKEN_GROUPS structure. If ResetToDefault is TRUE, this parameter is ignored.

BufferLength

Specifies the size, in bytes, of the buffer pointed to by the PreviousState parameter. This parameter can be NULL if the PreviousState parameter is NULL.

PreviousState

Points to a buffer receiving a TOKEN_GROUPS structure containing the previous state of any groups the function modifies. The token must be open for TOKEN_QUERY access to use this parameter. This parameter can be NULL.

If a buffer is specified but it does not contain enough space to receive the complete list of modified groups, no group states are changed and the function fails. In this case, the function sets the variable pointed to by the ReturnLength parameter to the number of bytes required to hold the complete list of modified groups.

ReturnLength

Points to a variable set by the function that contains the actual number of bytes needed for the buffer pointed to by the PreviousState parameter. This parameter can be NULL and is ignored if PreviousState is NULL.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The information retrieved in the PreviousState parameter is formatted as a TOKEN_GROUPS structure. This means a pointer to the buffer can be passed as the NewState parameter in a subsequent call to the AdjustTokenGroups function, restoring the original state of the groups.

The NewState parameter can list groups to be changed that are not present in the access token. This does not affect the successful modification of the groups in the token.

Mandatory groups cannot be disabled. They are identified by the SE_GROUP_MANDATORY flag in the TOKEN_GROUPS structure. If an attempt is made to disable any mandatory groups, AdjustTokenGroups fails and leaves the state of all groups unchanged.

See Also

AdjustTokenPrivileges, GetTokenInformation, OpenProcessToken, OpenThreadToken, SetTokenInformation, TOKEN_GROUPS


AdjustTokenPrivileges

The AdjustTokenPrivileges function adjusts privileges in the specified access token. Enabling or disabling privileges in an access token requires TOKEN_ADJUST_PRIVILEGES access.

BOOL AdjustTokenPrivileges(

HANDLE  TokenHandle,	// handle of token that contains privileges
BOOL  DisableAllPrivileges,	// flag for disabling all privileges
PTOKEN_PRIVILEGES  NewState,	// address of new privilege information
DWORD  BufferLength,	// size of previous information buffer
PTOKEN_PRIVILEGES  PreviousState,	// address of previous information
PDWORD  ReturnLength	// address of required buffer size
);
Parameters

TokenHandle

Identifies the access token that contains the privileges to be modified.

DisableAllPrivileges

Specifies whether the function is to disable all of the token's privileges. If this value is TRUE, the privileges are disabled, and the NewState parameter is ignored. If it is FALSE, the function modifies privileges based on the information pointed to by the NewState parameter.

NewState

Points to a TOKEN_PRIVILEGES structure containing the privileges to be changed. If the DisableAllPrivileges 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 DisableAllPrivileges is TRUE, this parameter is ignored.

BufferLength

Specifies the size, in bytes, of the buffer pointed to by the PreviousState parameter. This parameter can be NULL if the PreviousState parameter is NULL.

PreviousState

Points to a buffer 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 ReturnLength parameter to the number of bytes required to hold the complete list of modified privileges.

ReturnLength

Points to a variable receiving the actual number of bytes needed for the buffer pointed to by the PreviousState parameter. This parameter can be NULL and is ignored if PreviousState is NULL.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The information retrieved in the PreviousState parameter is formatted as a TOKEN_PRIVILEGES structure. This means that a pointer to the buffer can be passed as the NewState parameter in a subsequent call to the AdjustTokenPrivileges function, restoring the original state of the privileges.

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


AdjustWindowRect

The AdjustWindowRect function calculates the required size of the window rectangle based on the desired client-rectangle size. The window rectangle can then be passed to the CreateWindowEx function to create a window whose client area is the desired size.

BOOL AdjustWindowRect(

LPRECT  lpRect,	// address of client-rectangle structure
DWORD  dwStyle,	// window styles
BOOL  bMenu	// menu-present flag
);
Parameters

lpRect

Points to a RECT structure that contains the coordinates of the top-left and bottom-right corners of the desired client area. When the function returns, the structure contains the coordinates of the top-left and bottom-right corners of the window to accommodate the desired client area.

dwStyle

Specifies the window styles of the window whose required size is to be calculated.

bMenu

Specifies whether the window has a menu.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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 also does not add extra rows when a menu bar wraps to two or more rows.

See Also

AdjustWindowRectEx, CreateWindowEx, RECT


AdjustWindowRectEx

The AdjustWindowRectEx function calculates the required size of the rectangle of a window with extended style based on the desired client-rectangle size. The window rectangle can then be passed to the CreateWindowEx function to create a window whose client area is the desired size.

BOOL AdjustWindowRectEx(

LPRECT  lpRect,	// address of client-rectangle structure
DWORD  dwStyle,	// window styles
BOOL  bMenu,	// menu-present flag
DWORD  dwExStyle	// extended style
);
Parameters

lpRect

Points to a RECT structure that contains the coordinates of the top-left and bottom-right corners of the desired client area. When the function returns, the structure contains the coordinates of the top-left and bottom-right corners of the window to accommodate the desired client area.

dwStyle

Specifies the window styles of the window whose required size is to be calculated.

bMenu

Specifies whether the window has a menu.

dwExStyle

Specifies the extended style of the window whose required size is to be calculated.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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 also does not add extra space when a menu bar wraps to two or more rows.

See Also

AdjustWindowRect, CreateWindowEx, RECT


AdvancedDocumentProperties

The AdvancedDocumentProperties function displays a printer-configuration dialog box for the specified printer, allowing the user to configure that printer.

LONG AdvancedDocumentProperties(

HWND  hWnd,	// handle of dialog box's parent window
HANDLE  hPrinter,	// handle of printer object
LPTSTR  pDeviceName,	// address of driver name
PDEVMODE  pDevModeOutput,	// address of modified device mode structure
PDEVMODE  pDevModeInput	// address of original device mode structure
);
Parameters

hWnd

Identifies the parent window of the printer-configuration dialog box.

hPrinter

Identifies a printer object.

pDeviceName

Points to a null-terminated string specifying the name of the device for which a printer-configuration dialog box should be displayed.

pDevModeOutput

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 pDevModeOutput to NULL.

pDevModeInput

Points to a DEVMODE structure that contains the configuration data used to initialize the controls of the printer-configuration dialog box.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application can obtain the printer handle identified by the hPrinter parameter by calling the OpenPrinter or AddPrinter function.

An application can obtain the name pointed to by the pDeviceName parameter by calling the GetPrinter function and then examining the pPrinterName member of the PRINTER_INFO_2 structure.

See Also

AddPrinter, DEVMODE, GetPrinter, OpenPrinter, PRINTER_INFO_2


AllocateAndInitializeSid

The AllocateAndInitializeSid function allocates and initializes a security identifier (SID) with up to eight subauthorities.

BOOL AllocateAndInitializeSid(

PSID_IDENTIFIER_AUTHORITY  pIdentifierAuthority,	// address of identifier authority
BYTE  nSubAuthorityCount,	// count of subauthorities
DWORD  dwSubAuthority0,	// subauthority 0
DWORD  dwSubAuthority1,	// subauthority 1
DWORD  dwSubAuthority2,	// subauthority 2
DWORD  dwSubAuthority3,	// subauthority 3
DWORD  dwSubAuthority4,	// subauthority 4
DWORD  dwSubAuthority5,	// subauthority 5
DWORD  dwSubAuthority6,	// subauthority 6
DWORD  dwSubAuthority7,	// subauthority 7
PSID  *pSid	// address of pointer to SID
);
Parameters

pIdentifierAuthority

Points to an SID_IDENTIFIER_AUTHORITY structure, giving the top-level identifier authority value to set in the SID.

nSubAuthorityCount

Specifies the number of subauthorities to place in the SID. This parameter also identifies how many of the subauthority parameters have meaningful values. This parameter must contain a value from 1 through 8.

For example, a value of 3 indicates that the subauthority values specified by the dwSubAuthority0, dwSubAuthority1, and dwSubAuthority2 parameters have meaningful values and to ignore the remainder.

dwSubAuthority0 through dwSubAuthority7

Specify subauthority values to place in the SID.

pSid

Points to a variable that receives the address of the allocated and initialized SID structure.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An SID allocated with this function must be freed by using the FreeSid function.

See Also

FreeSid, GetSidIdentifierAuthority, InitializeSid, SID_IDENTIFIER_AUTHORITY


AllocateLocallyUniqueId

The AllocateLocallyUniqueId function allocates a locally unique identifier (LUID).

BOOL AllocateLocallyUniqueId(

PLUID  Luid	// address of locally unique identifier
);
Parameters

Luid

Points to a buffer that receives the allocated LUID.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An LUID is unique only within a single session. The same LUID value can be used on different computers or on the same computer after it has been restarted.

See Also

LookupPrivilegeValue


AllocConsole

The AllocConsole function allocates a new console for the calling process.

BOOL AllocConsole(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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

See Also

CreateProcess, FreeConsole, GetStdHandle


AllocDStoCSAlias

The AllocDStoCSAlias function is obsolete. This function has no meaning in the 32-bit environment.


AllocResource

The AllocResource function is not implemented in the Win32 API. Win32-based applications should use the LoadResource, LockResource, and FindResource functions.


AllocSelector

The AllocSelector function is not implemented in the Win32 API. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


AngleArc

The AngleArc function draws a line segment and an arc. The line segment is drawn from the current position to the beginning of the arc. The arc is drawn along the perimeter of a circle with the given radius and center. The length of the arc is defined by the given start and sweep angles.

BOOL AngleArc(

HDC  hdc,	// handle 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
);
Parameters

hdc

Identifies a device context.

X

Specifies the logical x-coordinate of the center of the circle.

Y

Specifies the logical y-coordinate of the center of the circle.

dwRadius

Specifies the radius, in logical units, of the circle. This value must be positive.

eStartAngle

Specifies the start angle, in degrees, relative to the x-axis.

eSweepAngle

Specifies the sweep angle, in degrees, relative to the starting angle.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The AngleArc function moves the current position to the ending point of the arc.

The arc drawn by this function may appear to be elliptical, depending on the current transformation and mapping mode. Before drawing the arc, AngleArc draws the line segment from the current position to the beginning of the arc.

The arc is drawn by constructing an imaginary circle around the specified center point with the specified radius. The starting point of the arc is determined by measuring counterclockwise from the x-axis of the circle by the number of degrees in the start angle. The ending point is similarly located by measuring counterclockwise from the starting point by the number of degrees in the sweep angle.

If the sweep angle is greater than 360 degrees, the arc is swept multiple times.

This function draws lines by using the current pen. The figure is not filled.

See Also

Arc, ArcTo, MoveToEx


AnimatePalette

The AnimatePalette function replaces entries in the specified logical palette.

BOOL AnimatePalette(

HPALETTE  hpal,	// handle 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
);
Parameters

hpal

Identifies the logical palette.

iStartIndex

Specifies the first logical palette entry to be replaced.

cEntries

Specifies the number of entries to be replaced.

ppe

Points to the first member of an array of PALETTEENTRY structures used to replace the current entries.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

The AnimatePalette function only changes entries with the PC_RESERVED flag set in the corresponding palPalEntry member of the LOGPALETTE structure.

If the given palette is associated with the active window, the colors in the palette are replaced immediately.

See Also

CreatePalette, GetDeviceCaps, LOGPALETTE, PALETTEENTRY


AnsiLower

The AnsiLower function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharLower function, which should be used for new Win32-based applications.


AnsiLowerBuff

The AnsiLowerBuff function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharLowerBuff function, which should be used for new Win32-based applications.


AnsiNext

The AnsiNext function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharNext function, which should be used for new Win32-based applications.


AnsiPrev

The AnsiPrev function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharPrev function, which should be used for new Win32-based applications.


AnsiToOem

The AnsiToOem function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharToOem function, which should be used for new Win32-based applications.


AnsiToOemBuff

The AnsiToOemBuff function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharToOemBuff function, which should be used for new Win32-based applications.


AnsiUpper

The AnsiUpper function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharUpper function, which should be used for new Win32-based applications.


AnsiUpperBuff

The AnsiUpperBuff function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the CharUpperBuff function, which should be used for new Win32-based applications.


AnyPopup

The AnyPopup function indicates whether an owned, visible, top-level pop-up, or overlapped window exists on the screen. The function searches the entire Windows screen, not just the calling application's client area.

BOOL AnyPopup(VOID)

Parameters

This function has no parameters.

Return Value

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.

Remarks

AnyPopup is a Windows version 1.x function and is retained for compatibility purposes. It is generally not useful.

This function does not detect unowned pop-up windows or windows that do not have the WS_VISIBLE style bit set.

See Also

GetLastActivePopup, ShowOwnedPopups


AppendMenu

The AppendMenu function appends a new item to the end of the specified menu. An application can use this function to specify the content, appearance, and behavior of the menu item.

BOOL AppendMenu(

HMENU hMenu,	// handle of menu
UINT uFlags,	// menu item flags
UINT uIDNewItem,	// menu item identifier or pop-up menu handle
LPCTSTR lpNewItem	// menu item content
);
Parameters

hMenu

Identifies the menu to be changed.

uFlags

Specifies flags to control the appearance and behavior of the new menu item. This parameter can be a combination of the values listed in the following Remarks section.

uIDNewItem

Specifies either the identifier of the new menu item or, if the uFlags parameter is set to MF_POPUP, the handle of the pop-up menu.

lpNewItem

Specifies the content of the new menu item. The interpretation of lpNewItem depends on whether the uFlags parameter includes the MF_BITMAP, MF_OWNERDRAW, or MF_STRING flag, as follows:

Value	Description
MF_BITMAP	Contains a bitmap handle.
MF_OWNERDRAW	Contains a 32-bit value supplied by the application that can be used to maintain additional data related to the menu item. The value is in the itemData member of the structure pointed to by the lparam parameter of the WM_MEASURE or WM_DRAWITEM message sent when the menu is created or its appearance is updated.
MF_STRING	Contains a pointer to a null-terminated string.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

The following flags must be set in the uFlags parameter:

Value	Description
MF_BITMAP	Uses a bitmap as the item. The lpNewItem 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 SetMenuItemBitmaps), this flag displays the check mark bitmap next to the menu item.
MF_DISABLED	Disables the menu item so that it cannot be selected, but 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 uIDNewItem 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 lpNewItem and uIDNewItem parameters are ignored.
MF_STRING	Specifies that the menu item is a text string; the lpNewItem parameter points to the string.
MF_UNCHECKED	Does not place a check mark next to the item (default). If the application supplies check mark bitmaps (see SetMenuItemBitmaps), this flag displays the unchecked bitmap next to the menu item.
The following 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


Arc

The Arc function draws an elliptical arc.

BOOL Arc(

HDC  hdc,	// handle of device context
int  nLeftRect,	// x-coordinate of bounding rectangle's upper-left corner
int  nTopRect,	// y-coordinate of bounding rectangle's upper-left corner
int  nRightRect,	// x-coordinate of bounding rectangle's lower-right corner
int  nBottomRect,	// y-coordinate of bounding rectangle's lower-right corner
int  nXStartArc,	// first radial ending point
int  nYStartArc,	// first radial ending point
int  nXEndArc,	// second radial ending point
int  nYEndArc	// second radial ending point
);
Parameters

hdc

Identifies the device context where drawing takes place.

nLeftRect

Specifies the logical x-coordinate of the upper-left corner of the bounding rectangle.

Windows 95: The sum of nLeftRect plus nRightRect must be less than 32768.

nTopRect

Specifies the logical y-coordinate of the upper-left corner of the bounding rectangle.

Windows 95: The sum of nTopRect plus nBottomRect must be less than 32768.

nRightRect

Specifies the logical x-coordinate of the lower-right corner of the bounding rectangle.

Windows 95: The sum of nLeftRect plus nRightRect must be less than 32768.

nBottomRect

Specifies the logical y-coordinate of the lower-right corner of the bounding rectangle.

Windows 95: The sum of nTopRect plus nBottomRect must be less than 32768.

nXStartArc

Specifies the logical x-coordinate of the ending point of the radial line defining the starting point of the arc.

nYStartArc

Specifies the logical y-coordinate of the ending point of the radial line defining the starting point of the arc.

nXEndArc

Specifies the logical x-coordinate of the ending point of the radial line defining the ending point of the arc.

nYEndArc

Specifies the logical y-coordinate of the ending point of the radial line defining the ending point of the arc.

Return Value

If the arc is drawn, the return value is TRUE; otherwise, it is FALSE.

Remarks

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 in the current drawing direction from the point where it intersects the radial from the center of the bounding rectangle to the (nXStartArc, nYStartArc) point. The arc ends where it intersects the radial from the center of the bounding rectangle to the (nXEndArc, nYEndArc) point. If the starting point and ending point are the same, a complete ellipse is drawn.

The arc is drawn using the current pen; it is not filled.

The current position is neither used nor updated by Arc.

Windows 95: The drawing direction is always counterclockwise.

Windows NT: Use the GetArcDirection and SetArcDirection functions to get and set the current drawing direction for a device context. The default drawing direction is counterclockwise.

See Also

AngleArc, ArcTo, Chord, Ellipse, GetArcDirection, Pie, SetArcDirection


ArcTo

The ArcTo function draws an elliptical arc.

BOOL ArcTo(

HDC  hdc,	// handle of device context
int  nLeftRect,	// x-coordinate of bounding rectangle's upper-left corner
int  nTopRect,	// y-coordinate of bounding rectangle's upper-left corner
int  nRightRect,	// x-coordinate of bounding rectangle's lower-right corner
int  nBottomRect,	// y-coordinate of bounding rectangle's lower-right corner
int  nXRadial1,	// x-coordinate of the first radial ending point
int  nYRadial1,	// y-coordinate of the first radial ending point
int  nXRadial2,	// x-coordinate of the second radial ending point
int  nYRadial2	// y-coordinate of the second radial ending point
);
Parameters

hdc

Identifies the device context where drawing takes place.

nLeftRect

Specifies the logical x-coordinate of the upper-left corner of the bounding rectangle.

nTopRect

Specifies the logical y-coordinate of the upper-left corner of the bounding rectangle.

nRightRect

Specifies the logical x-coordinate of the lower-right corner of the bounding rectangle.

nBottomRect

Specifies the logical y-coordinate of the lower-right corner of the bounding rectangle.

nXRadial1

Specifies the logical x-coordinate of the endpoint of the radial defining the starting point of the arc.

nYRadial1

Specifies the logical y-coordinate of the endpoint of the radial defining the starting point of the arc.

nXRadial2

Specifies the logical x-coordinate of the endpoint of the radial defining the ending point of the arc.

nYRadial2

Specifies the logical y-coordinate of the endpoint of the radial defining the ending point of the arc.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

ArcTo is similar to the Arc function, except that the current position is updated.

The points (nLeftRect, nTopRect) and (nRightRect, nBottomRect) specify the bounding rectangle. An ellipse formed by the given bounding rectangle defines the curve of the arc. The arc extends counterclockwise from the point where it intersects the radial line from the center of the bounding rectangle to the (nXRadial1, nYRadial1) point. The arc ends where it intersects the radial line from the center of the bounding rectangle to the (nXRadial2, nYRadial2) point. If the starting point and ending point are the same, a complete ellipse is drawn.

A line is drawn from the current position to the starting point of the arc. If no error occurs, the current position is set to the ending point of the arc.

The arc is drawn using the current pen; it is not filled.

See Also

AngleArc, Arc, SetArcDirection


AreAllAccessesGranted

The AreAllAccessesGranted function checks whether a set of requested access rights has been granted. The access rights are represented as bit flags in a 32-bit access mask.

BOOL AreAllAccessesGranted(

DWORD  GrantedAccess,	// access mask for granted access rights
DWORD  DesiredAccess	// access mask for requested access rights
);
Parameters

GrantedAccess

An access mask that specifies the access rights that have been granted.

DesiredAccess

An access mask that specifies the access rights that have been requested. This mask must have been mapped from generic to specific and standard access rights, usually by calling the MapGenericMask function.

Return Value

If all the requested access rights have been granted, the return value is TRUE; otherwise, it is FALSE.

Remarks

The AreAllAccessesGranted function is commonly used by a server application to check the access rights of a client attempting to gain access to an object. When the bits set in the DesiredAccess parameter match the bits set in the GrantedAccess parameter, all requested rights have been granted.

See Also

AccessCheck, AreAnyAccessesGranted, MapGenericMask


AreAnyAccessesGranted

The AreAnyAccessesGranted function tests whether any of a set of requested access rights has been granted. The access rights are represented as bit flags in a 32-bit access mask.

BOOL AreAnyAccessesGranted(

DWORD  GrantedAccess,	// access mask for granted access rights
DWORD  DesiredAccess	// access mask for access rights requested
);
Parameters

GrantedAccess

Specifies the granted access mask.

DesiredAccess

Specifies the access mask to be requested. This mask must have been mapped from generic to specific and standard access rights, usually by calling the MapGenericMask function.

Return Value

If any of the requested access rights have been granted, the return value is TRUE; otherwise, it is FALSE.

Remarks

The AreAnyAccessesGranted function is often used by a server application to check the access rights of a client attempting to gain access to an object. When any of the bits set in the DesiredAccess parameter match the bits set in the GrantedAccess parameter, at least one of the requested access rights has been granted.

See Also

AccessCheck, AreAllAccessesGranted, MapGenericMask


AreFileApisANSI

The AreFileApisANSI function determines whether a set of Win32 file functions is using the ANSI or OEM character set code page. This function is useful for 8-bit console input and output operations.

BOOL AreFileApisANSI (VOID)

Parameters

This function has no parameters.

Return Value

If the set of Win32 file functions is using the ANSI code page, the return value is TRUE.

If the set of Win32 file functions is using the OEM code page, the return value is FALSE.

Remarks

The SetFileApisToOEM function causes a set of Win32 file functions to use the OEM code page. The SetFileApisToANSI function causes the same set of Win32 file functions to use the ANSI code page. Use the AreFileApisANSI function to determine which code page the set of file functions is currently using. For a discussion of their usage, please refer to the Remarks sections of SetFileApisToOEM and SetFileApisToANSI.

The following is the set of Win32 file functions whose code page is ascertained by the AreFileApisANSI function:

_lopen	GetDriveType	LoadLibrary
CopyFile	GetFileAttributes	LoadLibraryEx
CreateDirectory	GetFullPathName	MoveFile
CreateFile	GetModuleFileName	MoveFileEx
CreateProcess	GetModuleHandle	OpenFile
DeleteFile	GetSystemDirectory	RemoveDirectory
FindFirstFile	GetTempFileName	SearchPath
FindNextFile	GetTempPath	SetCurrentDirectory
GetCurrentDirectory	GetVolumeInformation	SetFileAttributes
GetDiskFreeSpace	GetWindowsDirectory
See Also

SetFileApisToANSI, SetFileApisToOEM


ArrangeIconicWindows

The ArrangeIconicWindows function arranges all the minimized (iconic) child windows of the specified parent window.

UINT ArrangeIconicWindows(

HWND  hWnd	// handle of parent window
);
Parameters

hWnd

Identifies the parent window.

Return Value

If the function succeeds, the return value is the height of one row of icons.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application that maintains its own minimized child windows can use 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

The AttachThreadInput function attaches the input processing mechanism of one thread to that of another thread.

BOOL AttachThreadInput(

DWORD  idAttach,	// thread to attach
DWORD  idAttachTo,	// thread to attach to
BOOL  fAttach	// attach or detach
);
Parameters

idAttach

Specifies the identifier of the thread to be attached to another thread.

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 is FALSE, the threads are detached.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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 the GetKeyState or GetKeyboardState function, is reset after a call to AttachThreadInput.

See Also

GetCurrentThreadId, GetKeyState, GetKeyboardState, GetWindowThreadProcessId, SetFocus


BackupEventLog

The BackupEventLog function saves the specified event log to a backup file. The function does not clear the event log.

BOOL BackupEventLog(

HANDLE  hEventLog,	// handle to event log
LPCTSTR  lpBackupFileName	// name of backup file
);
Parameters

hEventLog

Identifies the open event log. This handle is returned by the OpenEventLog or OpenBackupEventLog function.

lpBackupFileName

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the backup filename specifies a remote server, the event log handle must identify a log on the local computer. You cannot back up an event logfile from a remote server to a file on a remote server (even if the backup file and the original log are on the same server).

See Also

OpenBackupEventLog, OpenEventLog


BackupRead

The BackupRead function reads data associated with a specified file or directory into a buffer. You use this function to back up a file or directory.

BOOL BackupRead(

HANDLE  hFile,	// handle to file or directory
LPBYTE  lpBuffer,	// pointer to buffer to read to
DWORD  nNumberOfBytesToRead,	// number of bytes to read
LPDWORD  lpNumberOfBytesRead,	// pointer to variable to receive number of bytes read
BOOL  bAbort,	// termination type
BOOL  bProcessSecurity,	// process security flag
LPVOID  *lpContext	// pointer to pointer to internal context information
);
Parameters

hFile

Handle to the file or directory being backed up. The function reads data associated with this file. You obtain this handle by calling the CreateFile function.

The BackupRead function fails if CreateFile was called with the flag FILE_FLAG_NO_BUFFERING. In this case, the GetLastError function returns the value ERROR_INVALID_PARAMETER.

lpBuffer

Pointer to a buffer that the function writes data to.

nNumberOfBytesToRead

Specifies the length of the buffer.  The buffer size must be greater than the size of a WIN32_STREAM_ID structure.

lpNumberOfBytesRead

Pointer to a variable that, when the function returns, contains the number of bytes read.

If the function return value is TRUE, and the variable pointed to by lpNumberOfBytesRead is zero, then all the data associated with the file handle has been read.

bAbort

Indicates whether BackupRead terminated abnormally. If this value is TRUE, the operation terminates abnormally and all buffers are deallocated.

bProcessSecurity

Indicates whether the function will restore the access-control list (ACL) data for the file or directory.

If bProcessSecurity is TRUE, the ACL data will be backed up.

lpContext

Pointer to a variable that receives and holds a pointer to an internal data structure used by BackupRead to maintain context information during a backup operation.

You must set the variable pointed to by lpContext to NULL before the first call to BackupRead for the specified file or directory. The function allocates memory for the data structure, and then sets the variable to point to that structure. You must not change lpContext  or the variable that it points to between calls to BackupRead.

To release the memory used by the data structure, call BackupRead with the bAbort parameter set to TRUE when the backup operation is complete.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, indicating that an I/O error occurred. To get extended error information, call GetLastError.

Remarks

BackupRead processes all of the data pertaining to an opened object as a series of discrete byte streams. Each stream is preceded by a 32-bit aligned WIN32_STREAM_ID structure.

Streams must be processed in the same order in which they were written to the tape. This ordering enables applications to compare the data backed up against the data on the source device. The data returned by BackupRead is to be used only as input to the BackupWrite function. This data is returned as one large data stream divided into substreams. The substreams are separated by WIN32_STREAM_ID headers.

If an error occurs while BackupRead is reading, the calling process can skip the bad data by calling the BackupSeek function.

See Also

BackupWrite, BackupSeek, WIN32_STREAM_ID


BackupSeek

The BackupSeek function seeks forward in a data stream initially accessed by using the BackupRead or BackupWrite function.

BOOL BackupSeek(

HANDLE  hFile,	// handle of open file
DWORD  dwLowBytesToSeek,	// low-order 32 bits of number of bytes
DWORD  dwHighBytesToSeek,	// high-order 32 bits of number of bytes
LPDWORD  lpdwLowByteSeeked,	// address of number of bytes function seeks
LPDWORD  lpdwHighByteSeeked,	// address of number of bytes function seeks
LPVOID *  lpContext	//address of internal context information
);
Parameters

hFile

Identifies the file or directory being backed up. This handle is created by using the CreateFile function.

dwLowBytesToSeek

Specifies the low-order 32 bits of the number of bytes to seek.

dwHighBytesToSeek

Specifies the high-order 32 bits of the number of bytes to seek.

lpdwLowByteSeeked

Points to a doubleword that, when the function returns, contains the low-order 32 bits of the number of bytes the function actually seeks.

lpdwHighByteSeeked

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

Points to an internal data structure used by the function. This structure must be the same structure that was initialized by the BackupRead function. An application must not touch the contents of this structure.

Return Value

If the function could seek the requested amount, the function returns TRUE. Otherwise, it is FALSE.

Remarks

Applications use BackUpSeek to skip portions of a data stream that cause errors. This function does not seek across stream headers. If an application attempts to seek past the end of a substream, the function fails, the lpdwLowByteSeeked and lpdwHighByteSeeked parameters indicate the actual number of bytes the function seeks, and the file position is placed at the start of the next stream header.

See Also

BackupRead, BackupWrite, CreateFile


BackupWrite

The BackupWrite function writes a stream of data from a buffer to a specified file or directory. The data must be divided into substreams separated by WIN32_STREAM_ID structures. You use this function to restore a file or directory that has been backed up.

BOOL BackupWrite(

HANDLE  hFile,	// handle to file or directory
LPBYTE  lpBuffer,	// pointer to buffer containing data to write
DWORD  nNumberOfBytesToWrite,	// number of bytes to write
LPDWORD  lpNumberOfBytesWritten,	// pointer to variable to receive number of bytes written
BOOL  bAbort,	// termination type
BOOL  bProcessSecurity,	// process security
LPVOID  *lpContext	// pointer to pointer to internal context information
);
Parameters

hFile

Handle to the file or directory being restored. The function writes data to this file. You obtain this handle by calling the CreateFile function.

The BackupWrite function fails if CreateFile was called with the flag FILE_FLAG_NO_BUFFERING. In this case, the GetLastError function returns the value ERROR_INVALID_PARAMETER.

lpBuffer

Pointer to a buffer that the function writes data from.

nNumberOfBytesToWrite

Specifies the length of the buffer.  The buffer size must be greater than the size of a WIN32_STREAM_ID structure.

lpNumberOfBytesWritten

Pointer to a variable that, when the function returns, contains the number of bytes written.

bAbort

Specifies whether BackupWrite terminated abnormally. If this value is TRUE, the operation terminated abnormally and all buffers were deallocated.

bProcessSecurity

Specifies whether the function will restore the access-control list (ACL) data for the file or directory.

If bProcessSecurity is TRUE, you need to have specified  WRITE_OWNER and WRITE_DAC access when opening the file or directory handle. If the handle does not have those access rights, the operating system denies access to the ACL data, and ACL data restoration will not occur.

lpContext

Pointer to a variable that receives and holds a pointer to an internal data structure used by BackupWrite to maintain context information during a restore operation.

You must set the variable pointed to by lpContext to NULL before the first call to BackupWrite for the specified file or directory. The function allocates memory for the data structure, and then sets the variable to point to that structure. You must not change lpContext or the variable that it points to between calls to BackupWrite.

To release the memory used by the data structure, call BackupWrite with the bAbort parameter set to TRUE when the restore operation is complete.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, indicating that an I/O error occurred. To get extended error information, call GetLastError.

Remarks

The BACKUP_LINK stream type lets you restore files with hard links.

Data obtained by the BackupRead function should only be used as input to the BackupWrite function.

See Also

BackupRead, BackupSeek, CreateFile, WIN32_STREAM_ID


Beep

The Beep function generates simple tones on the speaker.

BOOL Beep(

DWORD  dwFreq,	// sound frequency, in hertz
DWORD  dwDuration	// sound duration, in milliseconds
);
Parameters

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 called again.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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, Beep is asynchronous, returning control immediately to its caller while the sound continues playing. The sound continues until the next call to Beep.


BeginDeferWindowPos

The BeginDeferWindowPos function allocates memory for a multiple-window − position structure and returns the handle of the structure.

HDWP BeginDeferWindowPos(

int  nNumWindows	// number of windows
);
Parameters

nNumWindows

Specifies the initial number of windows for which to store position information. The DeferWindowPos function increases the size of the structure, if necessary.

Return Value

If the function succeeds, the return value identifies the multiple-window − position structure. If insufficient system resources are available to allocate the structure, the return value is NULL.

Remarks

The multiple-window − position structure is an internal structure; an application cannot access it directly.

DeferWindowPos fills the multiple-window − position structure with information about the target position for one or more windows about to be moved. The EndDeferWindowPos function accepts the handle 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 or SWP_SHOWWINDOW flag set, none of the windows are repositioned.

If Windows must increase the size of the multiple-window − position structure beyond the initial size specified by the nNumWindows parameter but cannot allocate enough memory to do so, Windows fails the entire window positioning sequence (BeginDeferWindowPos, DeferWindowPos, and EndDeferWindowPos). By specifying the maximum size needed, an application can detect and process failure early in the process.

See Also

DeferWindowPos, EndDeferWindowPos, SetWindowPos


BeginPaint

The BeginPaint function prepares the specified window for painting and fills a PAINTSTRUCT structure with information about the painting.

HDC BeginPaint(

HWND  hwnd,	// handle of window
LPPAINTSTRUCT  lpPaint	// address of structure for paint information
);
Parameters

hwnd

Identifies the window to be repainted.

lpPaint

Points to the PAINTSTRUCT structure that will receive painting information.

Return Value

If the function succeeds, the return value is the handle of a display device context (DC) for the given window.

If the function fails, the return value is NULL, indicating that no display DC is available.

Remarks

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, PAINTSTRUCT, ValidateRect, ValidateRgn


BeginPath

The BeginPath function opens a path bracket in the specified device context (DC).

BOOL BeginPath(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the DC.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

After a path bracket is open, an application can begin calling GDI drawing functions to define the points that lie in the path. An application can close an open path bracket by calling the EndPath function.

When an application calls BeginPath for a 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


BeginUpdateResource

The BeginUpdateResource function returns a handle that can be used by the UpdateResource function to add, delete, or replace resources in an executable file.

HANDLE BeginUpdateResource(

LPCTSTR  pFileName,	// address of file in which to update resources
BOOL  bDeleteExistingResources	// deletion option
);
Parameters

pFileName

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 pFileName does not specify a full path, Windows searches for the file in the current directory.

bDeleteExistingResources

Specifies whether to delete the pFileName parameter's existing resources. If this parameter is TRUE, existing resources are deleted and the updated executable file includes only resources added with the UpdateResource function. If this parameter is FALSE, the updated executable file includes existing resources unless they are explicitly deleted or replaced by using UpdateResource.

Return Value

If the function succeeds, the return value is a handle that can be used by the UpdateResource and EndUpdateResource functions. The return value is NULL if the specified file is not an executable file, the executable file is already loaded, the file does not exist, or the file cannot be opened for writing. To get extended error information, call GetLastError.

See Also

EndUpdateResource, UpdateResource


bind

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

int bind (

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

s

A descriptor identifying an unbound socket.

addr

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

    struct sockaddr {

        u_short    sa_family;

        char       sa_data[14];

    };

namelen

The length of the addr.

Return Value

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

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEADDRINUSE	The specified address is already in use. (See the SO_REUSEADDR socket option under setsockopt.)
WSAEFAULT	The namelen argument is too small (less than the size of a struct sockaddr).
WSAEINPROGRESS	A blocking Windows Sockets call is in progress.
WSAEAFNOSUPPORT	The specified address family is not supported by this protocol.
WSAEINVAL	The socket is already bound to an address.
WSAENOBUFS	Not enough buffers available, too many connections.
WSAENOTSOCK	The descriptor is not a socket.
Remarks

This function is used on an unconnected datagram or stream socket, before subsequent calls to the connect or listen functions. When a socket is created with socket, it exists in a name space (address family), but it has no name assigned. The bind function establishes the local association (host address/port number) of the socket by assigning a local name to an unnamed socket.

In the Internet address family, a name consists of several components. For SOCK_DGRAM and SOCK_STREAM, the name consists of three parts: a host address, the protocol number (set implicitly to UDP or TCP, respectively), and a port number which identifies the application. If an application does not care what address is assigned to it, it may specify an Internet address equal to INADDR_ANY, a port equal to 0, or both. If the Internet address is equal to INADDR_ANY, any appropriate network interface will be used; this simplifies application programming in the presence of multi-homed hosts. If the port is specified as 0, the Windows Sockets implementation will assign a unique port to the application with a value between 1024 and 5000. The application may use getsockname after bind to learn the address that has been assigned to it, but note that getsockname will not necessarily fill in the Internet address until the socket is connected, since several Internet addresses may be valid if the host is multi-homed.

If an application needs to bind to an arbitrary port outside of the range 1024 to 5000, code similar to the following can be used:

SOCKADDR_IN sin;

SOCKET s;

u_short alport = IPPORT_RESERVED;

sin.sin_family = AF_INET;

sin.sin_addr.s_addr = 0;

for (;;) {

    sin.sin_port = htons(alport);

    if (bind(s, (LPSOCKADDR)&sin, sizeof (sin)) == 0) {

        /* it worked */

    }

    if ( GetLastError != WSAEADDRINUSE) {

        /* fail */

    }

    alport--;

    if (alport == IPPORT_RESERVED/2 ) {

        /* fail--all unassigned reserved ports are */

        /* in use. */

    }

}

See Also

connect, listen, getsockname, setsockopt, socket, WSACancelBlockingCall, WSAStartup


BitBlt

The BitBlt function performs a bit-block transfer of the color data corresponding to a rectangle of pixels from the specified source device context into a destination device context.

BOOL BitBlt(

HDC  hdcDest,	// handle of destination device context
int  nXDest,	// x-coordinate of destination rectangle's upper-left corner
int  nYDest,	// x-coordinate of destination rectangle's upper-left corner
int  nWidth,	// width of destination rectangle
int  nHeight,	// height of destination rectangle
HDC  hdcSrc,	// handle of source device context
int  nXSrc,	// x-coordinate of source rectangle's upper-left corner
int  nYSrc,	// y-coordinate of source rectangle's upper-left corner
DWORD  dwRop	// raster operation code
);
Parameters

hdcDest

Identifies the destination device context.

nXDest

Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.

nYDest

Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.

nWidth

Specifies the logical width of the source and destination rectangles.

nHeight

Specifies the logical height of the source and the destination rectangles.

hdcSrc

Identifies the source device context.

nXSrc

Specifies the logical x-coordinate of the upper-left corner of the source rectangle.

nYSrc

Specifies the logical y-coordinate of the upper-left corner of the source rectangle.

dwRop

Specifies a raster-operation code. These codes define how the color data for the source rectangle is to be combined with the color data for the destination rectangle to achieve the final color.

The following list shows some common raster operation codes:

Value	Description
BLACKNESS	Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
DSTINVERT	Inverts the destination rectangle.
MERGECOPY	Merges the colors of the source rectangle with the specified pattern by using the Boolean AND operator.
MERGEPAINT	Merges the colors of the inverted source rectangle with the colors of the destination rectangle by using the Boolean OR operator.
NOTSRCCOPY	Copies the inverted source rectangle to the destination.
NOTSRCERASE	Combines the colors of the source and destination rectangles by using the Boolean OR operator and then inverts the resultant color.
PATCOPY	Copies the specified pattern into the destination bitmap.
PATINVERT	Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean XOR operator.
PATPAINT	Combines the colors of the pattern with the colors of the inverted source rectangle by using the Boolean OR operator. The result of this operation is combined with the colors of the destination rectangle by using the Boolean OR operator.
SRCAND	Combines the colors of the source and destination rectangles by using the Boolean AND operator.
SRCCOPY	Copies the source rectangle directly to the destination rectangle.
SRCERASE	Combines the inverted colors of the destination rectangle with the colors of the source rectangle by using the Boolean AND operator.
SRCINVERT	Combines the colors of the source and destination rectangles by using the Boolean XOR operator.
SRCPAINT	Combines the colors of the source and destination rectangles by using the Boolean OR operator.
WHITENESS	Fills the destination rectangle using the color associated with index 1 in the physical palette. (This color is white for the default physical palette.)
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If a rotation or shear transformation is in effect in the source device context, BitBlt returns an error. If other transformations exist in the source device context (and a matching transformation is not in effect in the destination device context), the rectangle in the destination device context is stretched, compressed, or rotated as necessary.

If the color formats of the source and destination device contexts do not match, the BitBlt function converts the source color format to match the destination format.

When an enhanced metafile is being recorded, an error occurs if the source device context identifies an enhanced-metafile device context.

Not all devices support the BitBlt function. For more information, see the RC_BITBLT raster capability entry in GetDeviceCaps.

BitBlt returns an error if the source and destination device contexts represent different devices.

See Also

GetDeviceCaps, MaskBlt, PlgBlt, StretchBlt


BringWindowToTop

The BringWindowToTop function brings the specified window to the top of the Z order. If the window is a top-level window, it is activated. If the window is a child window, the top-level parent window associated with the child window is activated.

BOOL BringWindowToTop(

HWND  hWnd	// handle of window
);
Parameters

hWnd

Identifies the window to bring to the top of the Z order.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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. BringWindowToTop does not make a window a top-level window.

If an application is not in the foreground and wants to be in the foreground, it should call the SetForegroundWindow function.

See Also

SetWindowPos, SetActiveWindow, SetForegroundWindow


BroadcastSystemMessage  (preliminaryWindows 95)
BroadcastSystemMessage  (preliminary−Windows 95)

The BroadcastSystemMessage function sends a message to the given recipients. The recipients can be applications, installable drivers, Windows-based network drivers, system-level device drivers, or any combination of these system components.

long BroadcastSystemMessage(

DWORD  dwFlags,
LPDWORD  lpdwRecipients,
UINT  uiMessage,
WPARAM  wParam,
LPARAM  lParam
);
Parameters

dwFlags

Option flags. Can be a combination of the following values:

Value	Meaning
BSF_FLUSHDISK	Flush the disk after each recipient processes the message.
BSF_FORCEIFHUNG	Wait for the time-out period to elapse before returning, if a recipient appears to be in a hung state.
BSF_IGNORECURRENTTASK	Do not send the message to windows that belong to the current task. This prevents an application from receiving its own message.
BSF_LPARAMPOINTER	The lParam parameter is the address of a buffer.
BSF_NOHANG	Return without waiting for the time-out period to elapse if a recipient appears to be in a hung state.
BSF_POSTMESSAGE	Post the message. Do not use in combination with BSF_LPARAMPOINTER or BSF_QUERY.
BSF_QUERY	Send the message to one recipient at a time, sending to a subsequent recipient only if the current recipient returns TRUE.
lpdwRecipients

Address of a 32-bit variable that contains and receives information about the recipients of the message. The variable can be a combination of the following values:

Value	Meaning
BSM_ALLCOMPONENTS	Broadcast to all system components.
BSM_APPLICATIONS	Broadcast to applications.
BSM_INSTALLABLEDRIVERS	Broadcast to installable drivers.
BSM_NETDRIVER	Broadcast to Windows-based network drivers.
BSM_VXDS	Broadcast to all system-level device drivers.
When the function returns, this variable receives a combination of these values identifying which recipients actually received the message.

If this parameter is NULL, the function broadcasts to all components.

uiMessage

Identifier of the system message.

wParam

32-bit message-specific value.

lParam

32-bit message-specific value. If the lpdwRecipients parameter specifies the BSF_LPARAMPOINTER value, the lParam parameter must be the address of a buffer, and the first 16-bit value in the buffer must specify the total size of the buffer, in bytes.

Return Value

If the function succeeds, the return value is a positive value.

If the function is unable to broadcast the message, the return value is −1.

If the dwFlags parameter is BSF_QUERY and at least one recipient returned FALSE to the corresponding message, the return value is zero.

Remarks

If BSF_QUERY is not given, the function sends the given message to all requested recipients, ignoring values returned by those recipients.

If BSF_LPARAMPOINTER is given, the function may modify the address given by the lParam parameter to make the buffer available to requested recipients. It is recommended that the buffer itself contain no addresses, because these addresses will not be modified and may not be accessible to all requested recipients.


BrowseCallbackProc

Specifies an application-defined callback function used with the SHBrowseForFolder function. The browse dialog box calls this function to notify it about events. The BFFCALLBACK type defines a pointer to this callback function.

int BrowseCallbackProc(

HWND  hwnd,
UINT  uMsg,
LPARAM  lParam,
LPARAM  lpData
);
Parameters

hwnd

Handle of the browse dialog box. The callback function can send the following messages to this window:

BFFM_ENABLEOK	Enables the OK button if the wParam parameter is nonzero or disables it if wParam is zero.
BFFM_SETSELECTION	Selects the specified folder. The lParam parameter is the PIDL of the folder to select if wParam is FALSE, or it is the path of the folder otherwise.
BFFM_SETSTATUSTEXT	Sets the status text to the null-terminated string specified by the lParam parameter.
uMsg

Value identifying the event. This parameter can be one of the following values:

BFFM_INITIALIZED	The browse dialog box has finished initializing. lpData is NULL.
BFFM_SELCHANGED	The selection has changed. lpData is a pointer to the item identifier list for the newly selected folder.
lParam

Message-specific value. For more information, see the description of uMsg.

lpData

Application-defined value that was specified in the lParam member of the BROWSEINFO structure.

Return Value

Returns zero.

See Also

BROWSEINFO


BuildCommDCB

The BuildCommDCB function fills a specified DCB structure with the values in a specified string.

BOOL BuildCommDCB(

LPCTSTR  lpDef,	// address of device-control string
LPDCB  lpDCB	// address of device-control block
);
Parameters

lpDef

Points to a null-terminated string that specifies device-control information. The string must have the same form as the Windows NT or MS-DOS 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, but 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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The BuildCommDCB function adjusts only those members of the DCB structure that are specifically affected by the lpDef parameter, with the following exceptions:

•	If the specified baud rate is 110, the function sets the stop bits to 2 to remain compatible with the Windows NT or MS-DOS mode command.

•	By default, BuildCommDCB disables XON/XOFF and hardware flow control. To enable flow control, you must explicitly set the appropriate members of the DCB structure.

The BuildCommDCB function only fills in the members of the DCB structure. To apply these settings to a serial port, use the SetCommState function.

See Also

DCB, SetCommState


BuildCommDCBAndTimeouts

The BuildCommDCBAndTimeouts function translates a device-definition string into appropriate device-control block codes and then places these codes into a device control block. The function can also set up time-out values, including the possibility of no time-outs, for a device; the function's behavior in this regard varies based on the contents of the device-definition string.

BOOL BuildCommDCBAndTimeouts(

LPCTSTR  lpDef,	// address of the device-control string
LPDCB  lpDCB,	// address of the device-control block
LPCOMMTIMEOUTS  lpCommTimeouts	// address of comm. time-out structure
);
Parameters

lpDef

Points to a null-terminated string that specifies device-control information for the device. The function takes this string, parses it, and then sets appropriate values in the DCB structure pointed to by lpDCB.

lpDCB

Points to a DCB structure that the function fills with information from the device-control information string pointed to by lpDef. This DCB structure defines the control settings for a communications device.

lpCommTimeouts

Points to a COMMTIMEOUTS structure that the function can use to set device time-out values.

The BuildCommDcbAndTimeouts function modifies its time-out setting behavior based on the presence or absence of a "TO=xxx" substring in the string specified by lpDef:

•	If that string contains the substring "TO=ON", the function sets up total read and write time-out values for the device based on the time-out structure pointed to by lpCommTimeouts.

•	If that string contains the substring "TO=OFF", the function sets up the device with no time-outs.

•	If that string contains neither of the aforementioned "TO=xxx" substrings, the function ignores the time-out structure pointed to by lpCommTimeouts. The time-out structure will not be accessed.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

BuildCommDCB, COMMTIMEOUTS, DCB, GetCommTimeouts, SetCommTimeouts


CallMsgFilter

The CallMsgFilter function passes the specified message and hook code to the hook procedures associated with the WH_SYSMSGFILTER and zhooks. A WH_SYSMSGFILTER or WH_MSGFILTER hook procedure is an application-defined callback function that examines and, optionally, modifies messages for a dialog box, message box, menu, or scroll bar.

BOOL CallMsgFilter(

LPMSG  lpMsg,	// address of structure with message data
int  nCode	// hook code
);
Parameters

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.

Return Value

If the application should process the message further, the return value is zero; otherwise, it is nonzero.

Remarks

Windows calls CallMsgFilter to enable applications to examine and control the flow of messages during internal processing of dialog boxes, message boxes, menus, and scroll bars, or when the user activates a different window by pressing the ALT+TAB key combination.

An application installs a hook procedure by using the SetWindowsHookEx function.

See Also

MessageProc, MSG, SetWindowsHookEx, SysMsgProc


CallNamedPipe

The CallNamedPipe function connects to a message-type pipe (and waits if an instance of the pipe is not available), writes to and reads from the pipe, and then closes the pipe.

BOOL CallNamedPipe(

LPCTSTR  lpNamedPipeName,	// address of pipe name
LPVOID  lpInBuffer,	// address of write buffer
DWORD  nInBufferSize,	// size, in bytes, of write buffer
LPVOID  lpOutBuffer,	// address of read buffer
DWORD  nOutBufferSize,	// size, in bytes, of read buffer
LPDWORD  lpBytesRead,	// address of number of bytes read
DWORD  nTimeOut	// time-out time, in milliseconds
);
Parameters

lpNamedPipeName

Points to a null-terminated string specifying the pipe name.

lpInBuffer

Points to the buffer containing the data written to the pipe.

nInBufferSize

Specifies the size, in bytes, of the write buffer.

lpOutBuffer

Points to the buffer that receives the data read from the pipe.

nOutBufferSize

Specifies the size, in bytes, of the read buffer.

lpBytesRead

Points to a 32-bit variable that receives the number of bytes read from the pipe.

nTimeOut

Specifies the number of milliseconds to wait for the named pipe to be available. In addition to numeric values, the following special values can be specified:

Value	Meaning
NMPWAIT_NOWAIT	Does not wait for the named pipe. If the named pipe is not available, the function returns an error.
NMPWAIT_WAIT_FOREVER	Waits indefinitely.
NMPWAIT_USE_DEFAULT_WAIT	Uses the default time-out specified in a call to the CreateNamedPipe function.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Calling CallNamedPipe is equivalent to calling the CreateFile (or WaitNamedPipe, if CreateFile cannot open the pipe immediately), TransactNamedPipe, and CloseHandle functions. CreateFile is called with an access flag of GENERIC_READ | GENERIC_WRITE, an inherit handle flag of FALSE, and a share mode of zero (indicating no sharing of this pipe instance).

If the message written to the pipe by the server process is longer than nOutBufferSize, CallNamedPipe returns FALSE, and GetLastError returns ERROR_MORE_DATA. The remainder of the message is discarded, because CallNamedPipe closes the handle to the pipe before returning.

CallNamedPipe fails if the pipe is a byte-type pipe.

See Also

CloseHandle, CreateFile, CreateNamedPipe, TransactNamedPipe, WaitNamedPipe


CallNextHookEx

The CallNextHookEx function passes the hook information to the next hook procedure in the current hook chain. This function supersedes the DefHookProc function.

LRESULT CallNextHookEx(

HHOOK  hhk,	// handle 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
);
Parameters

hhk

Identifies the current hook. An application receives this handle as a result of a previous call to the SetWindowsHookEx function.

nCode

Specifies the hook code passed to the current hook procedure. The next hook procedure uses this code to determine how to process the hook information.

wParam

Specifies the wParam value passed to the current hook procedure. The meaning of this parameter depends on the type of hook associated with the current hook chain.

lParam

Specifies the lParam value passed to the current hook procedure. The meaning of this parameter depends on the type of hook associated with the current hook chain.

Return Value

If the function succeeds, the return value is the value returned by the next hook procedure in the chain. The current hook procedure must also return this value. The meaning of the return value depends on the hook type. For more information, see the descriptions of the individual hook procedures.

Remarks

Hook procedures are installed in chains for particular hook types. CallNextHookEx calls the next hook in the chain.

Calling CallNextHookEx is optional. A hook procedure can call this function either before or after processing the hook information. If a hook procedure does not call CallNextHookEx, Windows does not call the hook procedures installed before the current hook procedure was installed.

See Also

SetWindowsHook, SetWindowsHookEx, UnhookWindowsHook, UnhookWindowsHookEx


CallWindowProc

The CallWindowProc function passes message information to the specified window procedure.

LRESULT CallWindowProc(

WNDPROC  lpPrevWndFunc,	// address of previous procedure
HWND  hWnd,	// handle of window
UINT  Msg,	// message
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

lpPrevWndFunc

Pointer to the previous window procedure.

If this value is obtained by calling the GetWindowLong function with the nIndex parameter set to GWL_WNDPROC or DWL_DLGPROC, it is actually either the address of a window or dialog box procedure, or a handle representing that address.

hWnd

Identifies the window procedure to receive the message.

Msg

Specifies the message.

wParam

Specifies additional message-specific information. The contents of this parameter depend on the value of the Msg parameter.

lParam

Specifies additional message-specific information. The contents of this parameter depend on the value of the Msg parameter.

Return Value

The return value specifies the result of the message processing and depends on the message sent.

Remarks

Use the CallWindowProc function for window subclassing. Usually, all windows with the same class share one window procedure. A subclass is a window or set of windows with the same class whose messages are intercepted and processed by another window procedure (or procedures) before being passed to the window procedure of the class.

The SetWindowLong function creates the subclass by changing the window procedure associated with a particular window, causing Windows to call the new window procedure instead of the previous one. An application must pass any messages not processed by the new window procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a chain of window procedures.

If STRICT is defined, the lpPrevWndFunc parameter has the data type WNDPROC. The WNDPROC type is declared as follows:

LRESULT (CALLBACK* WNDPROC) (HWND, UINT, WPARAM, LPARAM);

If STRICT is not defined, the lpPrevWndFunc parameter has the data type FARPROC. The FARPROC type is declared as follows:

int (FAR WINAPI * FARPROC) ()

In C, the FARPROC declaration indicates a callback function that has an unspecified parameter list. In C++, however, the empty parameter list in the declaration indicates that a function has no parameters. This subtle distinction can break careless code. Following is one way to handle this situation:

#ifdef STRICT

  WNDPROC MyWindowProcedure

#else

  FARPROC MyWindowProcedure

#endif

...

    lResult = CallWindowProc(MyWindowProcedure, ...) ;

For further information about functions declared with empty argument lists, refer to The C++ Programming Language, Second Edition, by Bjarne Stroustrup.

Windows NT: The CallWindowProc function handles Unicode-to-ANSI conversion. You don't get the conversion if you call the window procedure directly.

See Also

FARPROC, GetWindowLong, SetClassLong, SetWindowLong, WNDPROC


CallWndProc

The CallWndProc hook procedure is an application-defined or library-defined callback function that the system calls whenever the SendMessage function is called. Before passing the message to the destination window procedure, the system passes the message to the hook procedure. The hook procedure can examine the message; it cannot modify it.

LRESULT CALLBACK CallWndProc(

int  nCode,	// hook code
WPARAM  wParam,	// current-process flag
LPARAM  lParam	// address of structure with message data
);
Parameters

nCode

Specifies whether the hook procedure must process the message. If nCode is HC_ACTION, the hook procedure must process the message. If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies whether the message is sent by the current process. If the message is sent by the current process, it is nonzero; otherwise, it is NULL.

lParam

Points to a CWPSTRUCT structure that contains details about the message.

Return Value

The return value should be zero.

Remarks

The CallWndProc hook procedure can examine the message, but it cannot modify it. After the hook procedure returns control to the system, the message is passed to the window procedure.

An application installs the hook procedure by specifying the WH_CALLWNDPROC hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

CallWndProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, CWPSTRUCT, SendMessage, SetWindowsHookEx


CallWndRetProc  (preliminaryWindows 95)
CallWndRetProc  (preliminary−Windows 95)

The CallWndRetProc hook procedure is an application-defined or library-defined callback function the system calls after the SendMessage function is called. After passing the message to the destination window procedure, the system passes the message to the hook procedure. The hook procedure can examine the message; it cannot modify it.

LRESULT CALLBACK CallWndRetProc(

int  nCode,	// hook code
WPARAM  wParam,	// current-process flag
LPARAM  lParam	// address of structure with message data
);
Parameters

nCode

Specifies whether the hook procedure must process the message. If nCode is HC_ACTION, the hook procedure must process the message. If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies whether the message is sent by the current process. If the message is sent by the current process, it is nonzero; otherwise, it is NULL.

lParam

Points to a CWPRETSTRUCT structure that contains details about the message.

Return Value

The return value should be zero.

Remarks

An application installs the hook procedure by specifying the WH_CALLWNDPROCRET hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

CallWndRetProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, CallWndProc, CWPRETSTRUCT, SendMessage, SetWindowsHookEx


CancelDC

The CancelDC function cancels any pending operation on the specified device context (DC).

BOOL CancelDC(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the DC.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The CancelDC function is used by multithreaded applications to cancel lengthy drawing operations. If thread A initiates a lengthy drawing operation, thread B may cancel that operation by calling this function.

If an operation is canceled, the affected thread returns an error and the result of its drawing operation is undefined. The results are also undefined if no drawing operation was in progress when the function was called.

See Also

CreateThread, GetCurrentThread


CascadeWindows  (preliminaryWindows 95)
CascadeWindows  (preliminary−Windows 95)

The CascadeWindows function cascades the specified windows or the child windows of the specified parent window.

WORD WINAPI CascadeWindows(

HWND hwndParent,	// handle of parent window
UINT wHow,	// types of windows not to arrange
CONST RECT * lpRect,	// rectangle to arrange windows in
UINT cKids,	// number of windows to arrange
const HWND FAR * lpKids	// array of window handles
);
Parameters

hwndParent

Identifies the parent window. If this parameter is NULL, the desktop window is assumed.

wHow

Specifies a cascade flag. The only flag currently available, MDITILE_SKIPDISABLED, prevents disabled MDI child windows from being cascaded.

lpRect

Points to a SMALL_RECT structure that specifies the rectangular area, in screen coordinates, within which the windows are arranged. This parameter can be NULL, in which case the client area of the parent window is used.

cKids

Specifies the number of elements in the array specified by the lpKids parameter. This parameter is ignored if lpKids is NULL.

lpKids

Points to an array of window handles identifying the windows to arrange. If this parameter is NULL, the child windows of the specified parent window (or of the desktop window) are arranged.

Return Value

If the function succeeds, the return value is the number of windows arranged.

If the function fails, the return value is zero.

See Also

SMALL_RECT


Catch

The Catch function is not implemented in the Win32 API.

Structured exception handling is built into the Win32 API. For more information about structured exception handling, see Structured Exception Handling.


CBTProc

The CBTProc hook procedure is an application-defined or library-defined callback function that the system calls before activating, creating, destroying, minimizing, maximizing, moving, or sizing a window; before completing a system command; before removing a mouse or keyboard event from the system message queue; before setting the keyboard focus; or before synchronizing with the system message queue. The value returned by the hook procedure determines whether Windows allows or prevents one of these operations. A computer-based training (CBT) application uses this hook procedure to receive useful notifications from the system.

LRESULT CALLBACK CBTProc(

int  nCode,	// hook code
WPARAM  wParam,	// depends on hook code
LPARAM  lParam	// depends on hook code
);
Parameters

nCode

Specifies a code that the hook procedure uses to determine how to process the message. This parameter can be one of the following values:

Value	Meaning
HCBT_ACTIVATE	The system is about to activate a window.
HCBT_CLICKSKIPPED	The system has removed a mouse message from the system message queue. Upon receiving this hook code, a CBT application must install a WH_JOURNALPLAYBACK hook procedure in response to the mouse message.
HCBT_CREATEWND	A window is about to be created. The system calls the hook procedure before sending the WM_CREATE or WM_NCCREATE message to the window. If the hook procedure returns a nonzero value, the system destroys the window; the CreateWindow function returns NULL, but the WM_DESTROY message is not sent to the window. If the hook procedure returns zero, the window is created normally.
	At the time of the HCBT_CREATEWND notification, the window has been created, but its final size and position may not have been determined and its parent window may not have been established. It is possible to send messages to the newly created window, although it has not yet received WM_NCCREATE or WM_CREATE messages. It is also possible to change the position in the Z order of the newly created window by modifying the hwndInsertAfter member of the CBT_CREATEWND structure.
HCBT_DESTROYWND	A window is about to be destroyed.
HCBT_KEYSKIPPED	The system has removed a keyboard message from the system message queue. Upon receiving this hook code, a CBT application must install a WH_JOURNALPLAYBACK hook procedure in response to the keyboard message.
HCBT_MINMAX	A window is about to be minimized or maximized.
HCBT_MOVESIZE	A window is about to be moved or sized.
HCBT_QS	The system has retrieved a WM_QUEUESYNC message from the system message queue.
HCBT_SETFOCUS	A window is about to receive the keyboard focus.
HCBT_SYSCOMMAND	A system command is about to be carried out. This allows a CBT application to prevent task switching by means of hot keys.
If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Depends on the nCode parameter. For details, see the following Remarks section.

lParam

Depends on the nCode parameter. For details, see the following Remarks section.

Return Value

For operations corresponding to the following CBT hook codes, the return value must be 0 to allow the operation, or 1 to prevent it:

HCBT_ACTIVATE
HCBT_CREATEWND
HCBT_DESTROYWND
HCBT_MINMAX
HCBT_MOVESIZE
HCBT_SETFOCUS
HCBT_SYSCOMMAND

For operations corresponding to the following CBT hook codes, the return value is ignored:

HCBT_CLICKSKIPPED
HCBT_KEYSKIPPED
HCBT_QS

Remarks

The hook procedure should not install a WH_JOURNALPLAYBACK hook 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.  The HCBT_CLICKSKIPPED value is sent to a CBTProc hook procedure only if a WH_MOUSE hook is installed. For a list of hit-test codes, see WM_NCHITTEST .
HCBT_CREATEWND	Specifies the handle of the new window.	Specifies a long pointer to a CBT_CREATEWND structure containing initialization parameters for the window. The parameters include the coordinates and dimensions of the window. By changing these parameters, a CBTProc hook procedure can set the initial size and position of the window.
HCBT_DESTROYWND	Specifies the handle 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. The HCBT_KEYSKIPPED value is sent to a CBTProc hook procedure only if a WH_KEYBOARD hook is installed. For more information, see the WM_KEYUP or WM_KEYDOWN message.
HCBT_MINMAX	Specifies the handle 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 ShowWindow. 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. By changing the values in the structure, a CBTProc hook procedure can set the final coordinates of the window.
HCBT_QS	Is undefined and must be zero.	Is undefined and must be zero.
HCBT_SETFOCUS	Specifies the handle 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. For more information about system-command values, see WM_SYSCOMMAND.	Contains the same data as the lParam value of a WM_SYSCOMMAND message: If a system menu command is chosen with the mouse, the low-order word contains the x-coordinate of the cursor, in screen coordinates, and the high-order word contains the y-coordinate; otherwise, the parameter is not used.
CBTProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, CreateWindow, SetWindowsHookEx, WM_SYSCOMMAND


ChangeClipboardChain

The ChangeClipboardChain function removes a specified window from the chain of clipboard viewers.

BOOL ChangeClipboardChain(

HWND  hWndRemove,	// handle of window to remove
HWND  hWndNewNext	// handle of next window
);
Parameters

hWndRemove

Identifies the window to be removed from the chain. The handle must have been passed to the SetClipboardViewer function.

hWndNewNext

Identifies the window that follows the hWndRemove window in the clipboard viewer chain. (This is the handle returned by SetClipboardViewer, unless the sequence was changed in response to a WM_CHANGECBCHAIN message.)

Return Value

The return value indicates the result of passing the WM_CHANGECBCHAIN message to the windows in the clipboard viewer chain. Because a window in the chain typically returns FALSE when it processes WM_CHANGECBCHAIN, the return value from ChangeClipboardChain is typically FALSE. If there is only one window in the chain, the return value is typically TRUE.

Remarks

The window identified by hWndNewNext replaces the hWndRemove window in the chain. The SetClipboardViewer function sends a WM_CHANGECBCHAIN message to the first window in the clipboard viewer chain.

See Also

SetClipboardViewer, WM_CHANGECBCHAIN


ChangeMenu

The ChangeMenu function has been replaced by the following specialized functions, which are available on both Windows NT and Windows 95:

Function	Description
AppendMenu	Appends a menu item to the end of a menu.
InsertMenu	Inserts a menu item into a menu.
ModifyMenu	Modifies a menu item in a menu.
RemoveMenu	Removes a menu item from a menu; if it is a pop-up item, the corresponding pop-up menu is not destroyed.
Windows 95 only:

Instead of using AppendMenu, InsertMenu, and ModifyMenu, applications written exclusively for Window 95 should use the following new functions, which are available only on Windows 95.

Function	Description
GetMenuItemInfo	Windows 95 only: Gets information about a menu item.
InsertMenuItem	Windows 95 only: Inserts a new menu item at the specified position in a menu bar or pop-up menu.
SetMenuItemInfo	Windows 95 only: Changes information about a menu item.
Applications written for versions earlier than Windows 3.0 can continue to call ChangeMenu . Applications written for Windows versions 3.0 and later should call these new functions.


ChangeSelector

The ChangeSelector function is not implemented in the Win32 API. Win32-based applications running on Windows NT can use the VirtualLock and VirtualUnlock functions.


ChangeServiceConfig

The ChangeServiceConfig function changes the configuration parameters of a service.

BOOL ChangeServiceConfig(

SC_HANDLE  hService,	// handle of service
DWORD  dwServiceType,	// type of service
DWORD  dwStartType,	// when to start service
DWORD  dwErrorControl,	// severity if service fails to start
LPCTSTR  lpBinaryPathName,	// address of service binary file name
LPCTSTR  lpLoadOrderGroup,	// address of load ordering group name
LPDWORD  lpdwTagId,	// address of variable to get tag identifier
LPCTSTR  lpDependencies,	// address of array of dependency names
LPCTSTR  lpServiceStartName,	// address of account name of service
LPCTSTR  lpPassword,	// address of password for service account
LPCTSTR  lpDisplayName	// address of display name
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or CreateService function and must have SERVICE_CHANGE_CONFIG access.

dwServiceType

A set of bit flags that specify the type of service. Specify SERVICE_NO_CHANGE if you are not changing the existing service type; otherwise, specify one of the following service type flags to indicate the service type. In addition, if you specify either of the SERVICE_WIN32 flags, you can also specify the SERVICE_INTERACTIVE_PROCESS flag to enable the service process to interact with the desktop.

Value	Meaning
SERVICE_WIN32_OWN_PROCESS	A service type flag that specifies a Win32 service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS	A service type flag that specifies a Win32 service that shares a process with other services.
SERVICE_KERNEL_DRIVER	A service type flag that specifies a Windows NT device driver.
SERVICE_FILE_SYSTEM_DRIVER	A service type flag that specifies a Windows NT file system driver.
SERVICE_INTERACTIVE_PROCESS	A flag that enables a Win32 service process to interact with the desktop.
dwStartType

Specifies when to start the service. This value can be the service type SERVICE_NO_CHANGE if the existing start type is not modified, or one of the following values can be specified:

Value	Meaning
SERVICE_BOOT_START	Specifies a device driver started by the operating system loader. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_SYSTEM_START	Specifies a device driver started by the IoInitSystem function. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_AUTO_START	Specifies a device driver or Win32 service started by the service control manager automatically during system startup.
SERVICE_DEMAND_START	Specifies a device driver or Win32 service started by the service control manager when a process calls the StartService function.
SERVICE_DISABLED	Specifies a device driver or Win32 service that can no longer be started.
dwErrorControl

Specifies the severity of the error if this service fails to start during startup, and determines the action taken by the startup program if failure occurs. One of the following values can be specified:

Value	Meaning
SERVICE_ERROR_IGNORE	The startup (boot) program logs the error but continues the startup operation.
SERVICE_ERROR_NORMAL	The startup program logs the error and puts up a message box pop-up but continues the startup operation.
SERVICE_ERROR_SEVERE	The startup program logs the error. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.
SERVICE_ERROR_CRITICAL	The startup program logs the error, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration.
SERVICE_NO_CHANGE	The existing StartType value is not to be changed.
lpBinaryPathName

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.

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, the group is not modified. If it points to an empty string, the service does not belong to a group.

The registry has a list of load ordering groups located at

HKEY_LOCAL_MACHINES\System\CurrentControlSet
\Control\ServiceGroupOrder.

The startup program uses this list to load groups of services in a specified order with respect to the other groups in the list. You can place a service in a group so that another service can depend on the group.

The order in which a service starts is determined by the following criteria:

1.	The order of groups in the registry's load-ordering group list. Services in groups in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list, and then services that do not belong to a group.

2.	The service's dependencies listed in the lpDependencies parameter and the dependencies of other services dependent on the service.

lpdwTagId

Points to a 32-bit variable that receives a unique tag value for this service in the group specified in the lpLoadOrderGroup parameter. If no tag is requested, this parameter can be NULL.

You can use a tag for ordering service startup within a load ordering group by specifying a tag order vector in the registry located at

HKEY_LOCAL_MACHINE\System\CurrentControlSet
\Control\GroupOrderList.

Tags are only evaluated for SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER type services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

lpDependencies

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.

lpServiceStartName

Points to a null-terminated string. If NULL is specified, the name is not modified. If the service type is SERVICE_WIN32_OWN_PROCESS, this name is the account name in the form of "DomainName\Username", which the service process will be logged on as when it runs. If the account belongs to the built-in domain, ".\Username" can be specified. Services of type SERVICE_WIN32_SHARE_PROCESS are not allowed to specify an account other than LocalSystem.

If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this name is the Windows NT driver object name (that is, \FileSystem\Rdr or \Driver\Xns), which the input and output (I/O) system uses to load the device driver. If NULL is specified, the driver is run with a default object name created by the I/O system, based on the service name.

lpPassword

Points to a null-terminated string that contains the password to the account name specified by the lpServiceStartName parameter if the service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS. If the pointer is NULL, the password is not modified. If it points to an empty string, the service has no password. If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this parameter is ignored.

lpDisplayName

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with SERVICE_CHANGE_CONFIG access.
ERROR_CIRCULAR_DEPENDENCY
	A circular service dependency was specified.
ERROR_DUP_NAME
	The display name already exists in the service controller's database, either as a service name or as another display name.
ERROR_INVALID_HANDLE
	The specified handle is invalid.
ERROR_INVALID_PARAMETER
	A parameter that was specified is invalid.
ERROR_INVALID_SERVICE_ACCOUNT
	The account name does not exist, or a service is specified to share the same binary file as an already installed service but with an account name that is not the same as the installed service.
ERROR_SERVICE_MARKED_FOR_DELETE
	The service has been marked for deletion.
Remarks

The ChangeServiceConfig function changes the configuration information for the specified service in the service control manager database. This configuration information is initially specified by the CreateService function and can be queried (except for the password parameter) by using the QueryServiceConfig function.

Any of the configuration parameters specified for this function can be left unchanged by specifying NULL for a string parameter or SERVICE_NO_CHANGE for a doubleword parameter.

If the configuration is changed for a service that is running, with the exception of lpDisplayName, the changes do not take effect until the service is stopped.

See Also

CreateService, OpenService, QueryServiceConfig, StartService


CharLower

The CharLower function converts a character string or a single character to lowercase. If the operand is a character string, the function converts the characters in place. This function supersedes the AnsiLower function.

LPTSTR CharLower(

LPTSTR  lpsz	// single character or address of string
);
Parameters

lpsz

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.

Return Value

If the operand is a character string, the function returns a pointer to the converted string. Since the string is converted in place, the return value is equal to lpsz.

If the operand is a single character, the return value is a 32-bit value whose high-order word is zero, and low-order word contains the converted character.

There is no indication of success or failure. Failure is rare.

Remarks

Windows NT: To make the conversion, the function uses the language driver for the current language selected by the user at setup or by using the Control Panel. If no language has been selected, Windows completes the conversion by using internal default mapping. The conversion is made based on the code page associated with the process locale.

Windows 95: The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows 95 does not have language drivers.

See Also

CharLowerBuff, CharUpper, CharUpperBuff


CharLowerBuff

The CharLowerBuff function converts uppercase characters in a buffer to lowercase characters. The function converts the characters in place. The function supersedes the AnsiLowerBuff function.

DWORD CharLowerBuff(

LPTSTR  lpsz,	// points to buffer containing characters to process
DWORD  cchLength	// number of bytes or characters to process
);
Parameters

lpsz

Points to a buffer containing one or more characters to process.

cchLength

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the buffer pointed to by lpsz.

The function examines each character, and converts uppercase characters to lowercase characters. The function examines the number of bytes or characters indicated by cchLength, even if one or more characters are null characters.

Return Value

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) processed.

For example, if CharLowerBuff("Acme of Operating Systems", 10) succeeds, the return value is 10.

Remarks

Windows NT: To make the conversion, the function uses the language driver for the current language selected by the user at setup or by using the Control Panel. If no language has been selected, Windows completes the conversion by using internal default mapping. The conversion is made based on the code page associated with the process locale.

Windows 95: The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows 95 does not have language drivers.

See Also

CharLower, CharUpper, CharUpperBuff


CharNext

The CharNext function returns a pointer to the next character in a string. This function supersedes the AnsiNext function.

LPTSTR CharNext(

LPCTSTR  lpsz	// address of current character
);
Parameters

lpsz

Points to a character in a null-terminated string.

Return Value

If the function succeeds, the return value is a pointer to the next character in the string, or to the terminating null character if at the end of the string.

If lpsz points to the terminating null character, the return value is equal to lpsz.

See Also

CharPrev


CharPrev

The CharPrev function returns a pointer to the preceding character in a string. This function supersedes the AnsiPrev function.

LPTSTR CharPrev(

LPCTSTR  lpszStart,	// address of first character
LPCTSTR  lpszCurrent	// address of current character
);
Parameters

lpszStart

Points to the beginning of the string.

lpszCurrent

Points to a character in a null-terminated string.

Return Value

If the function succeeds, the return value is a pointer to the preceding character in the string, or to the first character in the string if the lpszCurrent parameter equals the lpszStart parameter.

See Also

CharNext


CharToOem

The CharToOem function translates a string into the OEM-defined character set. (OEM stands for original equipment manufacturer.) This function supersedes the AnsiToOem function.

BOOL CharToOem(

LPCTSTR  lpszSrc,	// address of string to translate
LPSTR  lpszDst	// address of translated string
);
Parameters

lpszSrc

Points to the null-terminated string to translate.

lpszDst

Points to the buffer for the translated string. If the CharToOem function is being used as an ANSI function, the string can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc parameter. This cannot be done if CharToOem is being used as a wide-character function.

Return Value

The return value is always TRUE.

See Also

CharToOemBuff, OemToChar, OemToCharBuff


CharToOemBuff

The CharToOemBuff function translates a specified number of characters in a string into the OEM-defined character set. (OEM stands for original equipment manufacturer.) This function supersedes the AnsiToOemBuff function.

BOOL CharToOemBuff(

LPCTSTR  lpszSrc,	// address of string to translate
LPSTR  lpszDst,	// address of translated string
DWORD  cchDstLength	// length of string to translate, in characters
);
Parameters

lpszSrc

Points to the null-terminated string to translate.

lpszDst

Points to the buffer for the translated string. If the CharToOemBuff function is being used as an ANSI function, the string can be translated in place by setting the lpszDst parameter to the same address as the lpszSrc parameter. This cannot be done if CharToOemBuff is being used as a wide-character function.

cchDstLength

Specifies the number of characters to translate in the string identified by the lpszSrc parameter.

Return Value

The return value is always TRUE.

See Also

CharToOem, OemToChar, OemToCharBuff


CharUpper

The CharUpper function converts a character string or a single character to uppercase. If the operand is a character string, the function converts the characters in place. This function supersedes the AnsiUpper function.

LPTSTR CharUpper(

LPTSTR  lpsz	// single character or address of string
);
Parameters

lpsz

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.

Return Value

If the operand is a character string, the function returns a pointer to the converted string. Since the string is converted in place, the return value is equal to lpsz.

If the operand is a single character, the return value is a 32-bit value whose high-order word is zero, and low-order word contains the converted character.

There is no indication of success or failure. Failure is rare.

Remarks

Windows NT: To make the conversion, the function uses the language driver for the current language selected by the user at setup or by using the Control Panel. If no language has been selected, Windows completes the conversion by using internal default mapping. The conversion is made based on the code page associated with the process locale.

Windows 95: The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows 95 does not have language drivers.

See Also

CharLower, CharLowerBuff, CharUpperBuff


CharUpperBuff

The CharUpperBuff function converts lowercase characters in a buffer to uppercase characters. The function converts the characters in place. The function supersedes the AnsiUpperBuff function.

DWORD CharUpperBuff(

LPTSTR  lpsz,	// points to buffer containing characters to process
DWORD  cchLength	// number of characters to process
);
Parameters

lpsz

Points to a buffer containing one or more characters to process.

cchLength

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the buffer pointed to by lpsz.

The function examines each character, and converts lowercase characters to uppercase characters. The function examines the number of bytes or characters indicated by cchLength, even if one or more characters are null characters.

Return Value

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) processed.

For example, if CharUpperBuff("Zenith of API Sets", 10) succeeds, the return value is 10.

Remarks

Windows NT: To make the conversion, the function uses the language driver for the current language selected by the user at setup or by using the Control Panel. If no language has been selected, Windows completes the conversion by using internal default mapping. The conversion is made based on the code page associated with the process locale.

Windows 95: The function makes the conversion based on the information associated with the user's default locale, which is the locale selected by the user at setup or by using the Control Panel. Windows 95 does not have language drivers.

See Also

CharLower, CharLowerBuff, CharUpper


CheckColorsInGamut  (preliminaryWindows 95)
CheckColorsInGamut  (preliminary−Windows 95)

The CheckColorsInGamut function indicates whether the specified color values are within the gamut of the specified device.

BOOL CheckColorsInGamut(

HDC  hdc,
LPVOID  lpaRGBQuad,
LPVOID  lpResult,
DWORD  nCount
);
Parameters

hdc

Handle to a device context.

lpaRGBQuad

Pointer to an array of RGBQUAD structures that contains the color values to check.

lpResult

Pointer to an array of bytes that receives the results of the color checking.

nCount

Count of elements in the array.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

For each specified color value, CheckColorsInGamut sets the corresponding byte in the results buffer to either CM_IN_GAMUT or CM_OUT_OF_GAMUT.

See Also

RGBQUAD


CheckDlgButton

The CheckDlgButton function changes the check state of a button control.

BOOL CheckDlgButton(

HWND  hDlg,	// handle of dialog box
int  nIDButton,	// button-control identifier
UINT  uCheck	// check state
);
Parameters

hDlg

Identifies the dialog box that contains the button.

nIDButton

Identifies the button to modify.

uCheck

Specifies the check state of the button. This parameter can be one of the following values:

Value	Meaning
0	Sets the button state to unchecked. Same as the Windows 95 constant BST_UNCHECKED.
1	Sets the button state to checked. Same as the Windows 95 constant BST_CHECKED.
2	Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style. Same as the Windows 95 constant BST_INDETERMINATE.
BST_CHECKED	Windows 95 only: Sets the button state to checked.
BST_INDETERMINATE	Windows 95 only: Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.
BST_UNCHECKED	Windows 95 only: Sets the button state to unchecked
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The CheckDlgButton function sends a BM_SETCHECK message to the specified button control in the given dialog box.

See Also

CheckRadioButton, IsDlgButtonChecked


CheckMenuItem

The CheckMenuItem function sets the state of the specified menu item's check mark attribute to either checked or unchecked.

DWORD CheckMenuItem(

HMENU hmenu,	// handle of menu
UINT uIDCheckItem,	// menu item to check or uncheck
UINT uCheck	// menu item flags
);
Parameters

hmenu

Identifies the menu of interest.

uIDCheckItem

Specifies the menu item whose check-mark attribute is to be set, as determined by the uCheck parameter.

uCheck

Specifies flags that control the interpretation of the uIDCheckItem parameter and the state of the menu item's check-mark attribute. This parameter can be a combination of either MF_BYCOMMAND or MF_BYPOSITION and MF_CHECKED or MF_UNCHECKED.

Value	Meaning
MF_BYCOMMAND	Indicates that the uIDCheckItem parameter gives the identifier of the menu item. The MF_BYCOMMAND flag is the default, if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION	Indicates that the uIDCheckItem parameter gives the zero-based relative position of the menu item.
MF_CHECKED	Sets the check-mark attribute to the checked state.
MF_UNCHECKED	Sets the check-mark attribute to the unchecked state.
Return Value

The return value specifies the previous state of the menu item (either MF_CHECKED or MF_UNCHECKED). If the menu item does not exist, the return value is 0xFFFFFFFF.

Remarks

An item in a menu bar cannot have a check mark.

The uIDCheckItem parameter identifies a pop-up item or a command item. For a pop-up item, the uIDCheckItem parameter must specify the position of the item, because a pop-up item does not have an identifier. For a command item, the uIDCheckItem parameter can specify either the item's position or its identifier.

See Also

EnableMenuItem, GetMenuCheckMarkDimensions, GetMenuItemID, SetMenuItemBitmaps


CheckMenuRadioItem  (preliminaryWindows 95)
CheckMenuRadioItem  (preliminary−Windows 95)

The CheckMenuRadioItem function checks a specified menu item and makes it a radio item. At the same time, the function unchecks all other menu items in the associated group and clears the radio-item type flag for those items.

BOOL API CheckMenuRadioItem(

HMENU  hmenu,
UINT  idFirst,
UINT  idLast,
UINT  idCheck,
UINT  uFlags
);
Parameters

hmenu

Handle to the menu that contains the group of menu items.

idFirst

Identifier or position of the first menu item in the group.

idLast

Identifier or position of the last menu item in the group.

idCheck

Identifier or position of the menu item to check.

uFlags

Value specifying the meaning of idFirst, idLast, and idCheck. If this parameter is MF_BYCOMMAND, the other parameters specify menu item identifiers. If it is MF_BYPOSITION, the other parameters specify the menu item positions.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

Remarks

The CheckMenuRadioItem function sets the MFT_RADIOCHECK type flag and the MFS_CHECKED state for the item specified by idCheck and, at the same time, clears both flags for all other items in the group. The checked item is displayed using a bullet bitmap instead of a check-mark bitmap.

For more information about menu item type and state flags, see the MENUITEMINFO structure.

See Also

MENUITEMINFO


CheckRadioButton

The CheckRadioButton function adds a check mark to (checks) a specified radio button in a group and removes a check mark from (clears) all other radio buttons in the group.

BOOL CheckRadioButton(

HWND  hDlg,	// handle of dialog box
int  nIDFirstButton,	// identifier of first radio button in group
int  nIDLastButton,	// identifier of last radio button in group
int  nIDCheckButton	// identifier of radio button to select
);
Parameters

hDlg

Identifies the dialog box that contains the radio button.

nIDFirstButton

Specifies the identifier of the first radio button in the group.

nIDLastButton

Specifies the identifier of the last radio button in the group.

nIDCheckButton

Specifies the identifier of the radio button to select.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The CheckRadioButton function sends a BM_SETCHECK message to each of the radio buttons in the indicated group.

See Also

BM_SETCHECK, CheckDlgButton, IsDlgButtonChecked


ChildWindowFromPoint

The ChildWindowFromPoint function determines which, if any, of the child windows belonging to a parent window contains the specified point.

HWND ChildWindowFromPoint(

HWND  hWndParent,	// handle of parent window
POINT  Point	// structure with point coordinates
);
Parameters

hWndParent

Identifies the parent window.

Point

Specifies a POINT structure that defines the client coordinates of the point to be checked.

Return Value

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.

Remarks

Windows maintains an internal list, containing the handles of the child windows associated with a parent window. The order of the handles in the list depends on the Z order of the child windows. If more than one child window contains the given point, Windows returns the handle of the first window in the list that contains the point.

See Also

ChildWindowFromPointEx, POINT, WindowFromPoint


ChildWindowFromPointEx  (preliminaryWindows NT)
ChildWindowFromPointE  [image] x  (preliminary−Windows 95)

The ChildWindowFromPointEx function determines which, if any, of the child windows belonging to the given parent window contains the specified point. The function can ignore invisible, disabled, and transparent child windows.

HWND ChildWindowFromPointEx(

HWND  hwndParent,	// handle of parent window
POINT  pt,	// structure with point coordinates
UINT  uFlags	// skipping flags
);
Parameters

hwndParent

Identifies the parent window.

pt

Specifies a POINT structure that defines the client coordinates of the point to be checked.

uFlags

Specifies which child windows to skip. This parameter can be a combination of the following values:

Value	Meaning
CWP_ALL	Do not skip any child windows
CWP_SKIPINVISIBLE	Skip invisible child windows
CWP_SKIPDISABLED	Skip disabled child windows
CWP_SKIPTRANSPARENT	Skip transparent child windows
Return Value

If the function succeeds, the return value is the handle of the first child window that contains the point and meets the criteria specified by uFlags. If the point is within the parent window but not within any child window that meets the criteria, the return value is the handle of the parent window. If the point lies outside the parent window or if the function fails, the return value is NULL.

Remarks

Windows maintains an internal list that contains the handles of the child windows associated with a parent window. The order of the handles in the list depends on the Z order of the child windows. If more than one child window contains the given point, Windows returns the handle of the first window in the list that contains the point and meets the criteria specified by uFlags.

See Also

ChildWindowFromPoint, POINT, WindowFromPoint


ChooseColor

The ChooseColor function creates a system-defined dialog box from which the user can select a color.

BOOL ChooseColor(

LPCHOOSECOLOR  lpcc	// address of structure with initialization data
);
Parameters

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.

Return Value

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.

The CommDlgExtendedError function can be used to get extended error information, which may be one of the following values:

CDERR_FINDRESFAILURE	CDERR_MEMLOCKFAILURE
CDERR_INITIALIZATION	CDERR_NOHINSTANCE
CDERR_LOCKRESFAILURE	CDERR_NOHOOK
CDERR_LOADRESFAILURE	CDERR_NOTEMPLATE
CDERR_LOADSTRFAILURE	CDERR_STRUCTSIZE
CDERR_MEMALLOCFAILURE
Remarks

The 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 (to which the lpfnHook member of the CHOOSECOLOR structure points) processes the WM_CTLCOLORDLG message, ChooseColor must return a handle for the brush that should be used to paint the control background.

See Also

CommDlgExtendedError, WM_CTLCOLORDLG, CHOOSECOLOR


ChooseFont

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.

BOOL ChooseFont(

LPCHOOSEFONT  lpcf	// address of structure with initialization data
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

The CommDlgExtendedError function can be used to get extended error information, which may be one of the following values:

CDERR_FINDRESFAILURE	CDERR_NOHINSTANCE
CDERR_INITIALIZATION	CDERR_NOHOOK
CDERR_LOCKRESFAILURE	CDERR_NOTEMPLATE
CDERR_LOADRESFAILURE	CDERR_STRUCTSIZE
CDERR_LOADSTRFAILURE	CFERR_MAXLESSTHANMIN
CDERR_MEMALLOCFAILURE	CFERR_NOFONTS
CDERR_MEMLOCKFAILURE
Remarks

If the hook function (to which the lpfnHook member of the CHOOSEFONT structure points) processes the WM_CTLCOLORDLG message, ChooseFont 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, LOGFONT


Chord

The Chord function draws a chord (a region bounded by the intersection of an ellipse and a line segment, called a "secant"). The chord is outlined by using the current pen and filled by using the current brush.

BOOL Chord(

HDC  hdc,	// handle of device context
int  nLeftRect,	// x-coordinate of the upper-left corner of the bounding rectangle
int  nTopRect,	// y-coordinate of the upper-left corner of the bounding rectangle
int  nRightRect,	// x-coordinate of the lower-right corner of the bounding rectangle
int  nBottomRect,	// y-coordinate of the lower-right corner of the bounding rectangle
int  nXRadial1,	// x-coordinate of the first radial's endpoint
int  nYRadial1,	// y-coordinate of the first radial's endpoint
int  nXRadial2,	// x-coordinate of the second radial's endpoint
int  nYRadial2	// y-coordinate of the second radial's endpoint
);
Parameters

hdc

Identifies the device context in which the chord appears.

nLeftRect

Specifies the x-coordinate of the upper-left corner of the bounding rectangle.

nTopRect

Specifies the y-coordinate of the upper-left corner of the bounding rectangle.

nRightRect

Specifies the x-coordinate of the lower-right corner of the bounding rectangle.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the bounding rectangle.

nXRadial1

Specifies the x-coordinate of the endpoint of the radial defining the beginning of the chord.

nYRadial1

Specifies the y-coordinate of the endpoint of the radial defining the beginning of the chord.

nXRadial2

Specifies the x-coordinate of the endpoint of the radial defining the end of the chord.

nYRadial2

Specifies the y-coordinate of the endpoint of the radial defining the end of the chord.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The curve of the chord is defined by an ellipse that fits the specified bounding rectangle. The curve begins at the point where the ellipse intersects the first radial and extends counterclockwise to the point where the ellipse intersects the second radial. (A radial is a line segment drawn from the center of the ellipse to a specified endpoint on the ellipse.) The chord is closed by drawing a line from the intersection of the first radial and the curve to the intersection of the second radial and the curve.

If the starting point and ending point of the curve are the same, a complete ellipse is drawn.

The current position is neither used nor updated by Chord.

See Also

AngleArc, Arc, ArcTo, Pie


ClearCommBreak

The ClearCommBreak function restores character transmission for a specified communications device and places the transmission line in a nonbreak state.

BOOL ClearCommBreak(

HANDLE  hFile	// handle of communications device
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A communications device is placed in a break state by the SetCommBreak or EscapeCommFunction function. Character transmission is then suspended until the break state is cleared by calling ClearCommBreak.

See Also

ClearCommError, CreateFile, EscapeCommFunction, SetCommBreak


ClearCommError

The ClearCommError function retrieves information about a communications error and reports the current status of a communications device. The function is called when a communications error occurs, and it clears the device's error flag to enable additional input and output (I/O) operations.

BOOL ClearCommError(

HANDLE  hFile,	// handle of communications device
LPDWORD  lpErrors,	// address of variable to receive error codes
LPCOMSTAT  lpStat	// address of buffer for communications status
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpErrors

Points to a 32-bit variable to be filled with a mask indicating the type of error. This parameter can be one or more of the following error values:

Value	Meaning
CE_BREAK	The hardware detected a break condition.
CE_DNS	Windows 95 only: A parallel device is not selected.
CE_FRAME	The hardware detected a framing error.
CE_IOE	An I/O error occurred during communications with the device.
CE_MODE	The requested mode is not supported, or the hFile parameter is invalid. If this value is specified, it is the only valid error.
CE_OOP	Windows 95 only: A parallel device signaled that it is out of paper.
CE_OVERRUN	A character-buffer overrun has occurred. The next character is lost.
CE_PTO	Windows 95 only: A time-out occurred on a parallel device.
CE_RXOVER	An input buffer overflow has occurred. There is either no room in the input buffer, or a character was received after the end-of-file (EOF) character.
CE_RXPARITY	The hardware detected a parity error.
CE_TXFULL	The application tried to transmit a character, but the output buffer was full.
lpStat

Points to a COMSTAT structure in which the device's status information is returned. If lpStat is NULL, no status information is returned.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If a communications port has been set up with a TRUE value for the fAbortOnError member of the setup DCB structure, the communications software will terminate all read and write operations on the communications port when a communications error occurs. No new read or write operations will be accepted until the application acknowledges the communications error by calling the ClearCommError function.

The ClearCommError function fills the status buffer pointed to by the lpStat parameter with the current status of the communications device specified by the hFile parameter.

See Also

ClearCommBreak, COMSTAT, CreateFile, DCB


ClearEventLog

The ClearEventLog function clears the specified event log, and optionally saves the current copy of the logfile to a backup file.

BOOL ClearEventLog(

HANDLE  hEventLog,	// handle to event log
LPCTSTR  lpBackupFileName	// name of backup file
);
Parameters

hEventLog

Identifies the event log to be cleared. This handle is returned by the OpenEventLog function.

lpBackupFileName

Points to the null-terminated string specifying the name of a file in which a current copy of the event logfile will be placed. If this file already exists, the function fails.

The backup filename may contain a server name to save the backup file on a remote server.

If the lpBackupFileName parameter is NULL, the current event logfile is not backed up.

Return Value

If the function succeeds, the return value is TRUE. The given event log has been backed up (if lpBackupFileName is not NULL) and then cleared.

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

Remarks

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 lpBackupFileName, ClearEventLog fails.

See Also

OpenEventLog


ClientToScreen

The ClientToScreen function converts the client coordinates of a specified point to screen coordinates.

BOOL ClientToScreen(

HWND  hWnd,	// window handle for source coordinates
LPPOINT  lpPoint	// address of structure containing screen coordinates
);
Parameters

hWnd

Identifies the window whose client area is used for the conversion.

lpPoint

Points to a POINT structure that contains the client coordinates to be converted. The new screen coordinates are copied into this structure if the function succeeds.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The ClientToScreen function replaces the client coordinates in the POINT structure with the screen coordinates. The screen coordinates are relative to the upper-left corner of the screen.

See Also

MapWindowPoints, POINT, ScreenToClient


ClipCursor

The ClipCursor function confines the cursor to a rectangular area on the screen. If a subsequent cursor position (set by the SetCursorPos function or the mouse) lies outside the rectangle, Windows automatically adjusts the position to keep the cursor inside the rectangular area.

BOOL ClipCursor(

CONST RECT * lpRect	// address of structure with rectangle
);
Parameters

lprc

Points to the RECT structure that contains the screen coordinates of the upper-left and lower-right corners of the confining rectangle. If this parameter is NULL, the cursor is free to move anywhere on the screen.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The cursor is a shared resource. If an application confines the cursor, it must release the cursor by using ClipCursor before relinquishing control to another application.

The calling process must have WINSTA_WRITEATTRIBUTES access to the window station.

See Also

GetClipCursor, GetCursorPos, RECT, SetCursorPos


CloseClipboard

The CloseClipboard function closes the clipboard.

BOOL CloseClipboard(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

When the window has finished examining or changing the clipboard, close the clipboard by calling CloseClipboard. This enables other windows to access the clipboard.

Do not place an object on the clipboard after calling CloseClipboard.

See Also

GetOpenClipboardWindow, OpenClipboard


CloseDesktop  (preliminaryWindows NT)
CloseDesktop  (preliminary−Windows NT)

The CloseDesktop function closes an open handle of a desktop object. A desktop is a secure object contained within a window station object. A desktop has a logical display surface and contains windows, menus and hooks.

BOOL CloseDesktop(

HDESK hDesktop	// handle of desktop to close
);
Parameters

hDesktop

Identifies the desktop to be closed. This handle is returned by the CreateDesktop and OpenDesktop functions.

Return Value

If the function succeeds, the return value is TRUE.

If the functions fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The CloseDesktop function will fail if any thread in the calling process is using the specified desktop handle or if the handle refers to the initial desktop of the calling process.

See Also

CreateDesktop, OpenDesktop


CloseEnhMetaFile

The CloseEnhMetaFile function closes an enhanced-metafile device context and returns a handle that identifies an enhanced-format metafile.

HENHMETAFILE CloseEnhMetaFile(

HDC  hdc	// handle of an enhanced-metafile device context
);
Parameters

hdc

Identifies an enhanced-metafile device context.

Return Value

If the function succeeds, the return value is a handle of an enhanced metafile.

If the function fails, the return value is NULL.

Remarks

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


CloseEventLog

The CloseEventLog function closes the specified event log.

BOOL CloseEventLog(

HANDLE  hEventLog	// handle to event log
);
Parameters

hEventLog

Identifies the event log to be closed. This handle is returned by the OpenEventLog function.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

OpenEventLog


CloseFigure

The CloseFigure function closes an open figure in a path.

BOOL CloseFigure(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context in which the figure will be closed.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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 then connects the lines by using the line join style. If a figure is closed by using the LineTo function instead of CloseFigure, end caps are used to create the corner instead of a join.

The CloseFigure function should only be called if there is an open path bracket in the specified device context.

A figure in a path is open unless it is explicitly closed by using this function. (A figure can be open even if the current point and the starting point of the figure are the same.)

After a call to CloseFigure, adding a line or curve to the path starts a new figure.

See Also

BeginPath, EndPath, ExtCreatePen, LineTo, MoveTo


CloseHandle

The CloseHandle function closes an open object handle.

BOOL CloseHandle(

HANDLE  hObject	// handle of object to close
);
Parameters

hObject

Identifies an open object handle.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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

CloseHandle is used to close handles returned by calls to the CreateFile function.

See Also

CreateFile, DeleteFile


CloseMetaFile

The CloseMetaFile function closes a metafile device context and returns a handle that identifies a Windows-format metafile.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the CloseEnhMetaFile function.

HMETAFILE CloseMetaFile(

HDC  hdc	// handle of metafile device context
);
Parameters

hdc

Identifies a metafile device context used to create a Windows-format metafile.

Return Value

If the function succeeds, the return value is a handle of a Windows-format metafile.

If the function fails, the return value is NULL.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should call the enhanced-format metafile functions.

To convert a Windows-format metafile into a new enhanced-format metafile, use the SetWinMetaFileBits function.

When an application no longer needs the Windows-format metafile handle, it should delete the handle by calling the DeleteMetaFile function.

See Also

BeginPath, CloseEnhMetaFile, CopyMetaFile, CreateMetaFile, DeleteMetaFile, EnumMetaFile, GetMetaFileBitsEx, PlayMetaFile, PolyBezier, SetWinMetaFileBits, SetWorldTransform


ClosePrinter

The ClosePrinter function closes the specified printer object.

BOOL ClosePrinter(

HANDLE  hPrinter	// handle of printer object
);
Parameters

hPrinter

Identifies the printer object to be closed.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AddPrinter, OpenPrinter


CloseServiceHandle

The CloseServiceHandle function closes a handle to a service control manager database as returned by the OpenSCManager function, or it closes a handle to a service object as returned by either the OpenService or CreateService function.

BOOL CloseServiceHandle(

SC_HANDLE  hSCObject	// handle of service or service control manager database
);
Parameters

hSCObject

Identifies the service control manager database or the service object to close.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error code may be set by the service control manager. Other error codes may be set by registry functions that are called by the service control manager.

Value	Meaning
ERROR_INVALID_HANDLE	The specified handle is invalid.
Remarks

The CloseServiceHandle function does not destroy the service control manager object referred to by the handle. A service control manager object cannot be destroyed. A service object can be destroyed by calling the DeleteService function.

See Also

CreateService, DeleteService, OpenSCManager, OpenService


closesocket

The Windows Sockets closesocket function closes a socket.

int closesocket (

SOCKET s
);
Parameters

s

A descriptor identifying a socket.

Return Value

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

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSAEINPROGRESS	A blocking Windows Sockets call is in progress.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
WSAEWOULDBLOCK	The socket is marked as nonblocking and SO_LINGER is set to a nonzero timeout value.
Remarks

This function closes a socket. More precisely, it releases the socket descriptor s, so that further references to s will fail with the error WSAENOTSOCK. If this is the last reference to the underlying socket, the associated naming information and queued data are discarded.

The semantics of closesocket are affected by the socket options SO_LINGER and SO_DONTLINGER as follows:

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

If SO_LINGER is set with a nonzero timeout interval, the closesocket call blocks until the remaining data has been sent or until the timeout expires. This is called a "graceful disconnect." Note that if the socket is set to nonblocking and SO_LINGER is set to a nonzero timeout, the call to closesocket will fail with an error of WSAEWOULDBLOCK.

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

See Also

accept, socket, ioctlsocket, setsockopt, WSAAsyncSelect, WSACancelBlockingCall, WSAStartup


CloseSound

The CloseSound function has been deleted.

See Also

Beep, MessageBeep


CloseWindow

The CloseWindow function minimizes (but does not destroy) the specified window.

BOOL CloseWindow(

HWND  hWnd	// handle of window to minimize
);
Parameters

hWnd

Identifies the window to be minimized.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The window is minimized by reducing it to the size of an icon and moving the window to the icon area of the screen. Windows displays the window's icon instead of the window and draws the window's title below the icon.

To destroy a window, an application must use the DestroyWindow function.

See Also

ArrangeIconicWindows, DestroyWindow, IsIconic, OpenIcon


CloseWindowStation  (preliminaryWindows NT)
CloseWindowStation  (preliminary−Windows NT)

The CloseWindowStation function closes an open window station handle.

BOOL CloseWindowStation(

HWINSTA hWinSta	// handle of window station to close
);
Parameters

hWinSta

Identifies the window station to be closed. This handle is returned by the CreateWindowStation and OpenWindowStation functions.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The CloseWindowStation function will fail if the handle being closed is for the window station assigned to the calling process.

See Also

SetProcessWindowStation


ColorMatchToTarget  (preliminaryWindows 95)
ColorMatchToTarget  (preliminary−Windows 95)

The ColorMatchToTarget function enables or disables preview for the specified device context. When preview is enabled, colors in subsequent output to the specified device context are displayed as they would appear on the target device. This is useful for checking how well the target maps the specified colors in an image. To enable preview, image color matching must be enabled for both the target and the preview device context.

BOOL ColorMatchToTarget(

HDC  hdc,
HDC  hdcTarget,
DWORD  uiAction
);
Parameters

hdc

Handle to the device context to use for preview, typically the display.

hdcTarget

Handle to the target device context, typically a printer.

uiAction

This parameter can have one of the following values:

Value	Meaning
CS_ENABLE	Enable preview; start matching colors through the target before displaying.
CS_DISABLE	Disable preview; stop matching colors through the target and restore the previous method for the preview device.
CS_DELETE_TRANSFORM	Disable preview and delete the color transformation used for previewing.
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

If you use ColorMatchToTarget to enable preview, your next call to this function must be to disable preview; you must not nest calls to enable preview. While preview is enabled, any changes you make to the color space or gamut matching method are temporarily ignored, but take effect when preview is disabled.


CombineRgn

The CombineRgn function combines two regions and stores the result in a third region. The two regions are combined according to the specified mode.

int CombineRgn(

HRGN  hrgnDest,	// handle of destination region
HRGN  hrgnSrc1,	// handle of source region
HRGN  hrgnSrc2,	// handle of source region
int  fnCombineMode	// region combining mode
);
Parameters

hrgnDest

Identifies a new region with dimensions defined by combining two other regions. (This region must exist before CombineRgn is called.)

hrgnSrc1

Identifies the first of two regions to be combined.

hrgnSrc2

Identifies the second of two regions to be combined.

fnCombineMode

Specifies a mode indicating how the two regions will be combined. This parameter can be one of the following values:

Value	Description
RGN_AND	Creates the intersection of the two combined regions.
RGN_COPY	Creates a copy of the region identified by hrgnSrc1.
RGN_DIFF	Combines the parts of hrgnSrc1 that are not part of hrgnSrc2.
RGN_OR	Creates the union of two combined regions.
RGN_XOR	Creates the union of two combined regions except for any overlapping areas.
Return Value

The return value specifies the type of the resulting region. It can be one of the following values:

Value	Meaning
NULLREGION	The region is empty.
SIMPLEREGION	The region is a single rectangle.
COMPLEXREGION	The region is more than a single rectangle.
ERROR	No region is created.
Remarks

The three regions need not be distinct. For example, the hrgnSrc1 parameter can equal the hrgnDest parameter.

See Also

CreateEllipticRgn, CreateEllipticRgnIndirect, CreatePolygonRgn, CreatePolyPolygonRgn, CreateRectRgn, CreateRectRgnIndirect, CreateRoundRectRgn


CombineTransform

The CombineTransform function concatenates two world-space to page-space transformations.

BOOL CombineTransform(

LPXFORM  lpxformResult,	// address of combined transformation
CONST XFORM *  lpxform1,	// address of first transformation
CONST XFORM *  lpxform2	// address of second transformation
);
Parameters

lpxformResult

Points to an XFORM structure that receives the combined transformation.

lpxform1

Points to an XFORM structure that identifies the first transformation.

lpxform2

Points to an XFORM structure that identifies the second transformation.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Applying the combined transformation has the same effect as applying the first transformation and then applying the second transformation.

The three transformations need not be distinct. For example, lpxform1 can point to the same XFORM structure as lpxformResult.

See Also

GetWorldTransform, ModifyWorldTransform, SetWorldTransform, XFORM


CommandLineToArgvW

The CommandLineToArgvW function parses a wide-character Unicode command-line string. It returns a pointer to a set of wide-character Unicode argument strings and a count of arguments, similar to the standard C run-time argv and argc values. The function provides a way to obtain a Unicode set of argv and argc values from a Unicode command-line string.

TCHAR **  CommandLineToArgvW(

TCHAR *  lpCmdLine,	// pointer to a command-line string
int *  *pNumArgs	// pointer to a variable that receives the argument count
);
Parameters

lpCmdLine

Pointer to a null-terminated Unicode command-line string. An application will usually directly pass on the value returned by a call to GetCommandLineW.

*pNumArgs

Pointer to an integer variable that the function sets to the count of arguments parsed.

Return Value

If the function succeeds, the return value is a non-NULL pointer to the constructed argument list, which is a set of Unicode wide-character argument strings. It is the caller's responsibility to free the argument list's memory when it is no longer needed.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

GetCommandLine


CommConfigDialog  (preliminaryWindows 95)
CommConfigDialog  (preliminary−Windows 95)

The CommConfigDialog function displays a driver-supplied configuration dialog box.

BOOL CommConfigDialog(

LPTSTR lpszName,	// address of device name string
HWND hWnd,	// handle of window
LPCOMMCONFIG lpCC,	// address of comm. configuration structure
);
Parameters

lpszName

Points to a null-terminated string specifying the name of the device for which a dialog box should be displayed.

hWnd

Identifies the window that owns the dialog box. This parameter can be any valid window handle, or it should be NULL if the dialog box is to have no owner.

lpCC

Points to a COMMCONFIG structure. This structure contains initial settings for the dialog box before the call, and changed values after the call.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

This function requires a dynamic-link library (DLL) provided by the communications hardware vendor.

See Also

COMMCONFIG


CommDlgExtendedError

The CommDlgExtendedError function identifies the cause of the most recent error that has occurred during the execution of one of the following common dialog box functions:

ChooseColor	GetOpenFileName
ChooseFont	GetSaveFileName
FindText	PrintDlg
GetFileTitle	ReplaceText
DWORD CommDlgExtendedError(VOID)

Parameters

This function has no parameters.

Return Value

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.

Remarks

Following are the possible CommDlgExtendedError return values and their meanings:

Value	Meaning
CDERR_DIALOGFAILURE	The common dialog box procedure's call to the DialogBox function failed. For example, this error occurs if the common dialog box call specifies an invalid window handle.
CDERR_FINDRESFAILURE	The common dialog box 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 specified 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 specified 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 specified 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 specified in the wDefault member of the DEVNAMES structure, but the printer described by the other structure members did not match the current default printer. (This error 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	The PrintDlg function failed during initialization, and there is no more specific extended error code to describe the failure. This is the generic default error code for the function.
PDERR_LOADDRVFAILURE	The PrintDlg function failed to load the device driver for the specified printer.
PDERR_NODEFAULTPRN	A default printer does not exist.
PDERR_NODEVICES	No printer drivers were found.
PDERR_PARSEFAILURE	The PrintDlg function failed to parse the strings in the [devices] section of the WIN.INI file.
PDERR_PRINTERNOTFOUND	The [devices] section of the WIN.INI file did not contain an entry for the requested printer.
PDERR_RETDEFFAILURE	The PD_RETURNDEFAULT flag was specified in the Flags member of the PRINTDLG structure, but the hDevMode or hDevNames member was nonzero.
PDERR_SETUPFAILURE	The PrintDlg function failed to load the required resources.
See Also

ChooseColor, CHOOSECOLOR, ChooseFont, CHOOSEFONT, DEVMODE, DEVNAMES, DialogBox, FINDREPLACE, FindText, GetFileTitle, GetOpenFileName, GetSaveFileName, OPENFILENAME, PrintDlg, PRINTDLG, RegisterWindowMessage, ReplaceText


CompareFileTime

The CompareFileTime function compares two 64-bit file times.

LONG CompareFileTime(

CONST FILETIME *  lpFileTime1,	// address of first file time
CONST FILETIME *  lpFileTime2	// address of second file time
);
Parameters

lpFileTime1

Points to a FILETIME structure that specifies the first 64-bit file time.

lpFileTime2

Points to a FILETIME structure that specifies the second 64-bit file time.

Return Value

If the function succeeds, the return value is one of the following values:

Value	Meaning
−1	First file time is less than second file time.
0	First file time is equal to second file time.
+1	First file time is greater than second file time.
See Also

GetFileTime, FILETIME


CompareString

The CompareString function compares two character strings, using the locale specified by the given identifier as the basis for the comparison.

int CompareString(

LCID  Locale,	// locale identifier
DWORD  dwCmpFlags,	// comparison-style options
LPCTSTR  lpString1,	// address of first string
int  cchCount1,	// size, in bytes or characters, of first string
LPCTSTR  lpString2,	// address of second string
int  cchCount2	// size, in bytes or characters, of second string
);
Parameters

Locale

Specifies the locale used for the comparison. This parameter can be one of the following predefined locale identifiers:

Value	Meaning
LOCALE_SYSTEM_DEFAULT	The system's default locale.
LOCALE_USER_DEFAULT	The current user's default locale.
This parameter can also be a locale identifier created by the MAKELCID macro.

dwCmpFlags

A set of flags that indicate how the function compares the two strings. By default, these flags are not set. This parameter can specify zero to get the default behavior, or it can be any combination of the following values:

Value	Meaning
NORM_IGNORECASE	Ignore case.
NORM_IGNOREKANATYPE	Do not differentiate between Hiragana and Katakana characters. Corresponding Hiragana and Katakana characters compare as equal.
NORM_IGNORENONSPACE	Ignore nonspacing characters.
NORM_IGNORESYMBOLS	Ignore symbols.
NORM_IGNOREWIDTH	Do not differentiate between a single-byte character and the same character as a double-byte character.
SORT_STRINGSORT	Treat punctuation the same as symbols.
lpString1

Points to the first string to be compared.

cchCount1

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the string pointed to by the lpString1 parameter. If this parameter is  − 1, the string is assumed to be null terminated and the length is calculated automatically.

lpString2

Points to the second string to be compared.

cchCount2

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the string pointed to by the lpString2 parameter. If this parameter is  − 1, the string is assumed to be null terminated and the length is calculated automatically.

Return Value

If the function succeeds, the return value is one of the following values:

Value	Meaning
1	The string pointed to by the lpString1 parameter is less in lexical value than the string pointed to by the lpString2 parameter.
2	The string pointed to by lpString1 is equal in lexical value to the string pointed to by lpString2.
3	The string pointed to by lpString1 is greater in lexical value than the string pointed to by lpString2.
If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

Notice that if the return value is 2, the two strings are "equal" in the collation sense, though not necessarily identical.

To maintain the C run-time convention of comparing strings, the value 2 can be subtracted from a 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	cant		sue's	sues
con	co-op		went	we're
coop	con		were	went
co-op	coop		we're	were
The lstrcmp and lstrcmpi functions use a word sort. The CompareString and LCMapString functions default to using a word sort, but use a string sort if their caller sets the SORT_STRINGSORT flag.

The CompareString function is optimized to run at the highest speed when dwCmpFlags is set to 0 or NORM_IGNORECASE, and cchCount1 and cchCount2 have the value -1.

The CompareString function ignores Arabic Kashidas during the comparison. Thus, if two strings are identical save for the presence of Kashidas, CompareString returns a value of 2; the strings are considered "equal" in the collation sense, though they are not necessarily identical.

See Also

FoldString, GetSystemDefaultLCID, GetUserDefaultLCID, LCMapString, lstrcmp, lstrcmpi,MAKELCID


ConfigurePort

The ConfigurePort function displays the port-configuration dialog box for a port on the specified server.

BOOL ConfigurePort(

LPTSTR  pName,	// address of server name
HWND  hWnd,	// handle of parent window of the dialog box
LPTSTR  pPortName	// address of port name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the given port exists. If this parameter is NULL, the port is local.

hWnd

Identifies the parent window of the port-configuration dialog box.

pPortName

Points to a null-terminated string that specifies the name of the port to be configured.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Before calling this function, an application should call the EnumPorts function to determine valid port names.

See Also

EnumPorts


connect

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

int connect (

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

s

A descriptor identifying an unconnected socket.

name

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

namelen

The length of the name.

Return Value

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

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

On a nonblocking socket, if the return value is SOCKET_ERROR, an application should call WSAGetLastError. If this indicates an error code of WSAEWOULDBLOCK, then your application can do one of the following:

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

•	If your application is using the message-based WSAAsyncSelect to indicate interest in connection events, then your application will receive an FD_CONNECT message when the connect operation is complete.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEADDRINUSE	The specified address is already in use.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets call is in progress.
WSAEADDRNOTAVAIL	The specified address is not available from the local computer.
WSAEAFNOSUPPORT	Addresses in the specified family cannot be used with this socket.
WSAECONNREFUSED	The attempt to connect was forcefully rejected.
WSAEDESTADDREQ	A destination address is required.
WSAEFAULT	The namelen argument is incorrect.
WSAEINVAL	The socket is not already bound to an address.
WSAEISCONN	The socket is already connected.
WSAEMFILE	No more file descriptors are available.
WSAENETUNREACH	The network can't be reached from this host at this time.
WSAENOBUFS	No buffer space is available. The socket cannot be connected.
WSAENOTSOCK	The descriptor is not a socket.
WSAETIMEDOUT	Attempt to connect timed out without establishing a connection.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the connection cannot be completed immediately. It is possible to select the socket while it is connecting by selecting it for writing.
Remarks

This function is used to create a connection to the specified foreign association. The parameter s specifies an unconnected datagram or stream socket If the socket is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound. Note that if the address field of the name structure is all zeroes, connect will return the error WSAEADDRNOTAVAIL.

For stream sockets (type SOCK_STREAM), an active connection is initiated to the foreign host using name (an address in the name space of the socket). When the socket call completes successfully, the socket is ready to send and receive data.

For a datagram socket (type SOCK_DGRAM), a default destination is set, which will be used on subsequent send and recv calls.

See Also

accept, bind, getsockname, recv, socket, select, send, WSAAsyncSelect, WSACancelBlockingCall, WSAStartup


ConnectNamedPipe

The ConnectNamedPipe function enables a named pipe server process to wait for a client process to connect to an instance of a named pipe. A client process connects by calling either the CreateFile or CallNamedPipe function.

BOOL ConnectNamedPipe(

HANDLE  hNamedPipe,	// handle of named pipe to connect
LPOVERLAPPED  lpOverlapped	// address of overlapped structure
);
Parameters

hNamedPipe

Identifies the server end of a named pipe instance. This handle is returned by the CreateNamedPipe function.

lpOverlapped

Points to an OVERLAPPED structure. This parameter can be NULL if an 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 following Remarks section.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A named pipe server process can use ConnectNamedPipe with a newly created pipe instance. It can also be used with an instance that was previously connected to another client process; in this case, the server process must first call the DisconnectNamedPipe function to disconnect the handle from the previous client before the handle can be reconnected to a new client. Otherwise, ConnectNamedPipe returns FALSE, and GetLastError returns ERROR_NO_DATA if the previous client has closed its handle or ERROR_PIPE_CONNECTED if it has not closed its handle.

The behavior of ConnectNamedPipe depends on two conditions: whether the pipe handle's wait mode is set to blocking or nonblocking and whether the function is set to execute synchronously or in overlapped mode. A server initially specifies a pipe handle's wait mode in the CreateNamedPipe function, and it can be changed by using the SetNamedPipeHandleState function. 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 the lpOverlapped parameter is NULL, the system attempts to execute the operation synchronously. If the attempt succeeds, the function does not return until a client is connected or an error occurs. If the attempt fails, the function may fail in unpredictable ways. Successful synchronous operations result in the function returning TRUE if a client connects after the function is called. If a client connects before the function is called, the function returns FALSE and GetLastError returns ERROR_PIPE_CONNECTED. This can happen if a client connects in the interval between the call to CreateNamedPipe and the call to ConnectNamedPipe. In this situation, there is a good connection between client and server, even though the function returns FALSE.

If lpOverlapped is not NULL, the operation executes asynchronously. The function returns immediately with a return value of FALSE. If a client process connects before the function is called, GetLastError returns ERROR_PIPE_CONNECTED. Otherwise, GetLastError returns ERROR_IO_PENDING, which indicates that the operation is executing in the background. When this happens, the event object in the OVERLAPPED structure is set to the nonsignaled state before ConnectNamedPipe returns, and it is set to the signaled state when a client connects to this instance of the pipe. The server process can use any of the wait functions — WaitForSingleObject, WaitForMultipleObjects, WaitForSingleObjectEx, WaitForMultipleObjectsEx, or SleepEx — to determine when the state of the event object is signaled, and it can then use the GetOverlappedResult function to determine the results of the ConnectNamedPipe operation.

If the specified pipe handle is in nonblocking mode, ConnectNamedPipe always returns immediately. In nonblocking mode, ConnectNamedPipe returns TRUE the first time it is called for a pipe instance that is disconnected from a previous client. This indicates that the pipe is now available to be connected to a new client process. In all other situations when the pipe handle is in nonblocking mode, ConnectNamedPipe returns FALSE. In these situations, GetLastError returns ERROR_PIPE_LISTENING if no client is connected, ERROR_PIPE_CONNECTED if a client is connected, and ERROR_NO_DATA if a previous client has closed its pipe handle but the server has not disconnected. Note that a good connection between client and server exists only after the ERROR_PIPE_CONNECTED error is received.

Note that nonblocking mode is supported for compatibility with Microsoft LAN Manager version 2.0, and it should not be used to achieve asynchronous input and output (I/O) with named pipes.

See Also

CallNamedPipe, CreateEvent, CreateFile, CreateNamedPipe, DisconnectNamedPipe, GetOverlappedResult, SetNamedPipeHandleState, SleepEx, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx, OVERLAPPED


ConnectToPrinterDlg

The ConnectToPrinterDlg function displays a dialog box that lets users browse and connect to printers on a network. If the user selects a printer, the function attempts to create a connection to it; if a suitable driver is not installed on the server, the user is given the option of creating a printer locally.

HANDLE ConnectToPrinterDlg (

HWND  hwnd,	// handle of parent window of dialog box
DWORD  Flags	// reserved for future use, must be zero
);
Parameters

hwnd

Specifies the parent window of the dialog box.

Flags

This parameter is reserved for future use. Set it to zero.

Return Value

If the function succeeds and the user selects a printer, the return value is a handle to the selected printer.

If the function fails, or the user cancels the dialog box without selecting a printer, the return value is NULL.

Remarks

The ConnectToPrinterDlg function attempts to create a connection to the selected printer. However, if the server on which the printer resides does not have a suitable driver installed, the function offers the user the option of creating a printer locally. A calling application can determine whether the function has created a printer locally by calling GetPrinter with a PRINTER_INFO_2 structure, then examining that structure's Attributes member.

An application should call DeletePrinter to delete a local printer. An application should call DeletePrinterConnection to delete a connection to a printer.

See Also

AddPrinterConnection, ClosePrinter, DeletePrinter, DeletePrinterConnection, GetPrinter, PRINTER_INFO_2


ContinueDebugEvent

The ContinueDebugEvent function enables a debugger to continue a thread that previously reported a debugging event.

BOOL ContinueDebugEvent(

DWORD  dwProcessId,	// process to continue
DWORD  dwThreadId,	// thread to continue
DWORD  dwContinueStatus	// continuation status
);
Parameters

dwProcessId

Identifies the process to continue.

dwThreadId

Identifies the thread to continue. The combination of process identifier and thread identifier must identify a thread that has previously reported a debugging event.

dwContinueStatus

Specifies how to continue the thread that reported the debugging event.

If the DBG_CONTINUE flag is specified for this parameter and the thread specified by the dwThreadId parameter previously reported an EXCEPTION_DEBUG_EVENT debugging event, the function stops all exception processing and continues the thread. For any other debugging event, this flag simply continues the thread.

If the DBG_EXCEPTION_NOT_HANDLED flag is specified for this parameter and the thread specified by dwThreadId previously reported an EXCEPTION_DEBUG_EVENT debugging event, the function continues exception processing. If this is a first-chance exception event, the search and dispatch logic of the structured exception handler is used; otherwise, the process is terminated. For any other debugging event, this flag simply continues the thread.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Only the thread that created dwProcessId 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, different actions occur. If the continued thread previously reported an EXIT_THREAD_DEBUG_EVENT debugging event, ContinueDebugEvent closes the handle the debugger has to the thread. If the continued thread previously reported an EXIT_PROCESS_DEBUG_EVENT debugging event, ContinueDebugEvent closes the handles the debugger has to the process and to the thread.

See Also

CreateProcess


ControlService

The ControlService function sends a control code to a Win32 service.

BOOL ControlService(

SC_HANDLE  hService,	// handle of service
DWORD  dwControl,	// control code
LPSERVICE_STATUS  lpServiceStatus	// address of service status structure
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or CreateService function. The access required for this handle depends on the dwControl code requested.

dwControl

Specifies the requested control code. This value can be one of the standard control codes in the table, or it can be a user-defined control code in the range of 128 to 255, inclusive. For user-defined control codes, the hService handle must have SERVICE_USER_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 hService handle must have SERVICE_STOP access.
SERVICE_CONTROL_PAUSE
	Requests the service to pause. The hService handle must have SERVICE_PAUSE_CONTINUE access.
SERVICE_CONTROL_CONTINUE
	Requests the paused service to resume. The hService handle must have SERVICE_PAUSE_CONTINUE access.
SERVICE_CONTROL_INTERROGATE
	Requests the service to update immediately its current status information to the service control manager. The hService handle must have SERVICE_INTERROGATE access.
SERVICE_CONTROL_SHUTDOWN
	The ControlService function fails if this control code is specified.
lpServiceStatus

Points to a SERVICE_STATUS structure where the latest status information of the service is returned. The information returned reflects the most recent status reported by the service to the service control manager.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with the necessary access.
ERROR_DEPENDENT_SERVICES_RUNNING
	The service cannot be stopped because other running services are dependent on it.
ERROR_INVALID_SERVICE_CONTROL
	The requested control code is not valid, or it is unacceptable to the service.
ERROR_SERVICE_CANNOT_ACCEPT_CTRL
	The requested control code cannot be sent to the service because the state of the service is SERVICE_STOPPED, SERVICE_START_PENDING, or SERVICE_STOP_PENDING.
ERROR_SERVICE_NOT_ACTIVE
	The service has not been started.
ERROR_SERVICE_REQUEST_TIMEOUT
	The service did not respond to the start request in a timely fashion.
Remarks

The ControlService function asks the service control manager to send the requested control code to the service. The service control manager sends the code if the service accepts the control and if the service is in a controllable state. The QueryServiceStatus or ControlService function returns a SERVICE_STATUS structure whose dwCurrentState and dwControlsAccepted members indicate the current state and controls accepted by a running Win32 service.

All running services accept the SERVICE_CONTROL_INTERROGATE control code by default. Each service specifies the other control codes that it accepts when it calls the SetServiceStatus function to report its status.

The following table shows the action of the service control manager in each of the possible service states:

Service state	Stop	Other controls
STOPPED	(c)	(c)
STOP_PENDING	(b)	(b)
START_PENDING	(a)	(b)
RUNNING	(a)	(a)
CONTINUE_PENDING	(a)	(a)
PAUSE_PENDING	(a)	(a)
PAUSED	(a)	(a)
(a) If the service accepts this control code, send the request to the service; otherwise, ControlService returns FALSE and GetLastError returns ERROR_INVALID_SERVICE_CONTROL.
(b) The service is not in a controllable state, so ControlService returns FALSE and GetLastError returns ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
(c) The service is not in a controllable state, so ControlService returns FALSE and GetLastError returns ERROR_SERVICE_NOT_ACTIVE.
See Also

CreateService, OpenService, QueryServiceStatus, SetServiceStatus, SERVICE_STATUS


ConvertDefaultLocale

The ConvertDefaultLocale function converts a special default locale value to an actual locale identifier.

LCID ConvertDefaultLocale(

LCID  Locale	// special default locale value to be converted
);
Parameters

Locale

A special default locale value that the function converts to an actual locale identifier.

The following list shows the special default locale values:

Value	Description
LOCALE_SYSTEM_DEFAULT	The system's default locale.
LOCALE_USER_DEFAULT	The current user's default locale.
zero	The language-neutral default locale. This is equivalent to the locale identifier created by calling the MAKELCID macro with a language identifier consisting of the LANG_NEUTRAL and SUBLANG_NEUTRAL values.
Any sublanguage neutral default locale	A locale identifier constructed by calling MAKELCID with a language identifier consisting of a primary language value, such as LANG_ENGLISH, and the SUBLANG_NEUTRAL value.
Return Value

If the function succeeds, the return value is the appropriate actual locale identifier.

If the function fails, the return value is the Locale parameter. The function fails when Locale is not one of the special default locale values listed above.

Remarks

A call to ConvertDefaultLocale(LOCALE_SYSTEM_DEFAULT) is equivalent to a call to GetSystemDefaultLCID. A call to ConvertDefaultLocale(LOCALE_USER_DEFAULT) is equivalent to a call to GetUserDefaultLCID.

For more information about locale identifiers, see Locales and Language Identifiers.

See Also

GetSystemDefaultLCID, GetUserDefaultLCID


CopyAcceleratorTable

The CopyAcceleratorTable function copies the specified accelerator table. This function is used to obtain the accelerator-table data that corresponds to an accelerator-table handle, or to determine the size of the accelerator-table data.

int CopyAcceleratorTable(

HACCEL  hAccelSrc,	// handle of accelerator table to copy
LPACCEL  lpAccelDst,	// address of structure receiving copy
int  cAccelEntries	// number of entries in table being copied
);
Parameters

hAccelSrc

Identifies the accelerator table to copy.

lpAccelDst

Points to an array of ACCEL structures where the accelerator-table information is to be copied.

cAccelEntries

Specifies the number of ACCEL structures to copy to the buffer pointed to by the lpAccelDst parameter.

Return Value

If lpAccelDst is NULL, the return value specifies the number of accelerator-table entries in the original table. Otherwise, it specifies the number of accelerator-table entries that were copied.

See Also

ACCEL, CreateAcceleratorTable, DestroyAcceleratorTable, LoadAccelerators, TranslateAccelerator


CopyCursor

The CopyCursor function copies a cursor.

HCURSOR CopyCursor(

HCURSOR  pcur	// handle of cursor to copy
);
Parameters

pcur

Identifies the cursor to be copied.

Return Value

If the function succeeds, the return value is the handle of the duplicate cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

CopyCursor enables an application or dynamic-link library (DLL) to obtain the handle 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


CopyEnhMetaFile

The CopyEnhMetaFile function copies the contents of an enhanced-format metafile to a specified file.

HENHMETAFILE CopyEnhMetaFile(

HENHMETAFILE  hemfSrc,	// handle of an enhanced metafile
LPCTSTR  lpszFile	// address of a filename string
);
Parameters

hemfSrc

Identifies the source-enhanced metafile.

lpszFile

Points to the name of the destination file. If this parameter is NULL, the source metafile is copied to memory.

Return Value

If the function succeeds, the return value is a handle of the copy of the enhanced metafile.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Where text arguments must use Unicode characters, use 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


CopyFile

The CopyFile function copies an existing file to a new file.

BOOL CopyFile(

LPCTSTR  lpExistingFileName,	// address of name of an existing file
LPCTSTR  lpNewFileName,	// address of filename to copy to
BOOL  bFailIfExists	// flag for operation if file exists
);
Parameters

lpExistingFileName

Points to a null-terminated string that specifies the name of an existing file.

lpNewFileName

Points to a null-terminated string that specifies the name of the new file.

bFailIfExists

Specifies how this operation is to proceed if a file of the same name as that specified by lpNewFileName already exists. If this parameter is TRUE and the new file already exists, the function fails. If this parameter is FALSE and the new file already exists, the function overwrites the existing file and succeeds.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Security attributes for the existing file are not copied to the new file.

File attributes (FILE_ATTRIBUTE_*) for the existing file are copied to the new file. For example, if an existing file has the FILE_ATTRIBUTE_READONLY file attribute, a copy created through a call to CopyFile will also have the FILE_ATTRIBUTE_READONLY file attribute. For further information on file attributes, see CreateFile.

See Also

CreateFile, MoveFile


CopyIcon

The CopyIcon function copies the specified icon from another module to the current module.

HICON CopyIcon(

HICON  hIcon	// handle of icon to copy
);
Parameters

hIcon

Identifies the icon to be copied.

Return Value

If the function succeeds, the return value is the handle of the duplicate icon.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CopyIcon function enables an application or dynamic-link library (DLL) to get its own handle 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, DrawIconEx


CopyImage  (preliminaryWindows 95)
CopyImage  (preliminary−Windows 95)

The CopyImage function creates a new image (icon, cursor, or bitmap) and copies the attributes of the given image to the new one. If necessary, the function stretches the bits to fit the desired size of the new image.

HANDLE CopyImage(

HANDLE  hImage,	// handle of the image to copy
UINT  uType,	// type of image to copy
int  cxDesired,	// desired width of new image
int  cyDesired,	// desired height of new image
UINT  fuFlags	// copy flags
);
Parameters

hinst

Identifies an instance of the module that contains the image to be copied.

uType

Specifies the type of image to be copied. This parameter can be one of the following values:

Value	Meaning
IMAGE_BITMAP	Copies a bitmap.
IMAGE_CURSOR	Copies a cursor.
IMAGE_ICON	Copies an icon.
cxDesired

Specifies the desired width, in pixels, of the image.

cyDesired

Specifies the desired height, in pixels, of the image.

fuFlags

Specifies a combination of the following values:

Value	Meaning
LR_COPYFROMRESOURCE	Reloads the given image resource before creating the copy.
LR_COPYDELETEORG	Deletes the original image after creating the copy.
LR_COPYRETURNORG	Creates an exact copy of the image, ignoring the cxDesired and cyDesired parameters.
LR_MONOCHROME	Creates a new monochrome image.
Return Value

If the function succeeds, the return value is the handle of the newly created image.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.


CopyLZFile

The CopyLZFile function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. For Win32-based applications, use the LZCopy function.


CopyMemory

The CopyMemory function copies a block of memory from one location to another.

VOID CopyMemory (

PVOID  Destination,	// address of copy destination
CONST VOID *  Source,	// address of block to copy
DWORD  Length	// size, in bytes, of block to copy
);
Parameters

Destination

Points to the starting address of the copied block's destination.

Source

Points to the starting address of the block of memory to copy.

Length

Specifies the size, in bytes, of the block of memory to copy.

Return Value

This function has no return value.

Remarks

If the source and destination blocks overlap, the results are undefined. For overlapped blocks, use the MoveMemory function.

See Also

FillMemory, MoveMemory, ZeroMemory


CopyMetaFile

The CopyMetaFile function copies the content of a Windows-format metafile to the specified file.

This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the CopyEnhMetaFile function.

HMETAFILE CopyMetaFile(

HMETAFILE  hmfSrc,	// handle of a Windows-format metafile
LPCTSTR  lpszFile	// address of a filename string
);
Parameters

hmfSrc

Identifies the source Windows-format metafile.

lpszFile

Points to the name of the destination file. If this parameter is NULL, the source metafile is copied to memory.

Return Value

If the function succeeds, the return value is a handle of the copy of the Windows-format metafile.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CopyMetaFile function supports only applications designed for Windows version 3.x. It does not record or play back the new graphics device interface functions, such as PolyBezier.

Where text arguments must use Unicode characters, use this function as a wide-character function. Where text arguments must use characters from the Windows 3.x character set, use this function as an ANSI function.

When the application no longer needs the Windows-format metafile handle, it should delete the handle by calling the DeleteMetaFile function.

See Also

DeleteMetaFile


CopyRect

The CopyRect function copies the coordinates of one rectangle to another.

BOOL CopyRect(

LPRECT  lprcDst,	// address of structure for destination rectangle
CONST RECT  *lprcSrc	// address of structure with source rectangle
);
Parameters

lprcDst

Points to the RECT structure that will receive the logical coordinates of the source rectangle.

lprcSrc

Points to the RECT structure whose coordinates are to be copied.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

RECT, SetRect, SetRectEmpty


CopySid

The CopySid function copies a security identifier (SID) to a buffer.

BOOL CopySid(

DWORD  nDestinationSidLength,	// size of buffer for copied SID
PSID  pDestinationSid,	// address of buffer for copied SID
PSID  pSourceSid	// address of source SID
);
Parameters

nDestinationSidLength

Specifies the length, in bytes, of the buffer receiving the copy of the SID.

pDestinationSid

Points to a buffer receiving a copy of the source SID structure.

pSourceSid

Points to a SID structure the function copies to the buffer pointed to by the pDestinationSid parameter.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application can use the CopySid function to make a copy of a SID in an access token (in a TOKEN_GROUPS structure, for instance) to use in an access-control entry.

See Also

AllocateAndInitializeSid, EqualSid, GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, InitializeSid, IsValidSid, SID


CountClipboardFormats

The CountClipboardFormats function retrieves the number of different data formats currently on the clipboard.

int CountClipboardFormats(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the number of different data formats currently on the clipboard.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

EnumClipboardFormats, RegisterClipboardFormat


CountVoiceNotes

The CountVoiceNotes function has been deleted.

See Also

Beep, MessageBeep


CPlApplet

The CPlApplet function is a library-defined callback function that serves as the entry point for a Control Panel application.

LONG APIENTRY CPlApplet(

HWND  hwndCPl,	// handle of Control Panel window
UINT  uMsg,	// message
LONG  lParam1,	// first message parameter
LONG  lParam2	// second message parameter
);
Parameters

hwndCPl

Identifies the main window of the controlling application.

uMsg

Specifies the message being sent to the Control Panel application.

lParam1

Specifies additional message-specific information.

lParam2

Specifies additional message-specific information.

Return Value

The return value depends on the message. For more information, see the descriptions of the individual Control Panel messages.

Remarks

Use the hwndCPl parameter for dialog boxes or other windows that require a handle of a parent window.


CreateAcceleratorTable

The CreateAcceleratorTable function creates an accelerator table.

HACCEL CreateAcceleratorTable(

LPACCEL  lpaccl,	// address of structure array with accelerator data
int  cEntries	// number of structures in the array
);
Parameters

lpaccl

Points to an array of ACCEL structures that describes the accelerator table.

cEntries

Specifies the number of ACCEL structures in the array.

Return Value

If the function succeeds, the return value is the handle of the created accelerator table; otherwise, it is NULL.

Remarks

Before an application closes, it must use the DestroyAcceleratorTable function to destroy each accelerator table that it created by using the CreateAcceleratorTable function.

See Also

ACCEL, CopyAcceleratorTable, DestroyAcceleratorTable, LoadAccelerators, TranslateAccelerator


 CreateBitmap

The CreateBitmap function creates a bitmap with the specified width, height, and color format (color planes and bits per pixel).

HBITMAP CreateBitmap(

int  nWidth,	// bitmap width, in pixels
int  nHeight,	// bitmap height, in pixels
UINT  cPlanes,	// number of color planes used by device
UINT  cBitsPerPel,	// number of bits required to identify a color
CONST VOID  *lpvBits	// address of array containing color data
);
Parameters

nWidth

Specifies the bitmap width, in pixels.

nHeight

Specifies the bitmap height, in pixels.

cPlanes

Specifies the number of color planes used by the device.

cBitsPerPel

Specifies the number of bits required to identify the color of a single pixel.

lpvBits

Points to an array of color data used to set the colors in a rectangle of pixels. Each scan line in the rectangle must be word aligned (scan lines that are not word aligned must be padded with zeros). If this parameter is NULL, the new bitmap is undefined.

Return Value

If the function succeeds, the return value is a handle of a bitmap.

If the function fails, the return value is NULL.

Remarks

After a bitmap is created, it can be selected into a device context by calling the SelectObject function.

While the CreateBitmap function can be used to create color bitmaps, for performance reasons applications should use CreateBitmap to create monochrome bitmaps and CreateCompatibleBitmap to create color bitmaps. When a color bitmap returned from CreateBitmap is selected into a device context, Windows must ensure that the bitmap matches the format of the device context it is being selected into. Since CreateCompatibleBitmap takes a device context, it returns a bitmap that has the same format as the specified device context. Because of this, subsequent calls to SelectObject are faster than with a color bitmap returned from CreateBitmap.

If the bitmap is monochrome, zeros represent the foreground color and ones represent the background color for the destination device context.

If an application sets the nWidth or nHeight parameters to zero, CreateBitmap returns the handle of a 1- by 1-pixel, monochrome bitmap.

See Also

CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIBitmap, DeleteObject, GetBitmapBits, SelectObject, SetBitmapBits


CreateBitmapIndirect

The CreateBitmapIndirect function creates a bitmap with the specified width, height, and color format (color planes and bits per pixel).

HBITMAP CreateBitmapIndirect(

CONST BITMAP *lpbm	// address of the bitmap data
);
Parameters

lpbm

Points to a BITMAP structure that contains information about the bitmap. If an application sets the bmWidth or bmHeight members to zero, CreateBitmapIndirect returns the handle of a 1- by 1-pixel, monochrome bitmap.

Return Value

If the function succeeds, the return value is a handle of the bitmap.

If the function fails, the return value is NULL.

Remarks

After a bitmap is created, it can be selected into a device context by calling the SelectObject function.

While the CreateBitmapIndirect function can be used to create color bitmaps, for performance reasons applications should use CreateBitmapIndirect to create monochrome bitmaps and CreateCompatibleBitmap to create color bitmaps. When a color bitmap returned from CreateBitmapIndirect is selected into a device context, Windows must ensure that the bitmap matches the format of the device context it is being selected into. Since CreateCompatibleBitmap takes a device context, it returns a bitmap that has the same format as the specified device context. Because of this, subsequent calls to SelectObject are faster than with a color bitmap returned from CreateBitmapIndirect.

If the bitmap is monochrome, zeros represent the foreground color and ones represent the background color for the destination device context.

See Also

BitBlt, BITMAP, CreateBitmap, CreateCompatibleBitmap, CreateDIBitmap, SelectObject


CreateBrushIndirect

The CreateBrushIndirect function creates a logical brush that has the specified style, color, and pattern.

HBRUSH CreateBrushIndirect(

CONST LOGBRUSH *  lplb	// address of structure describing brush
);
Parameters

lplb

Points to a LOGBRUSH structure that contains information about the brush.

Return Value

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

A brush is a bitmap that Windows uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreateBrushIndirect, it can select it into any device context by calling the SelectObject function.

A brush created by using a monochrome bitmap (one color plane, one bit per pixel) is drawn using the current text and background colors. Pixels represented by a bit set to 0 are drawn with the current text color; pixels represented by a bit set to 1 are drawn with the current background color.

If the lbStyle member of the LOGBRUSH structure pointed to by lplb is BS_PATTERN, the bitmap pointed to by the lbHatch member of that structure cannot be a DIB section. A DIB section is a bitmap created by CreateDibSection. If that bitmap is a DIB section, the CreateBrushIndirect function fails.

See Also

CreateDibSection, DeleteObject, GetBrushOrgEx, LOGBRUSH, SelectObject, SetBrushOrgEx


CreateCaret

The CreateCaret function creates a new shape for the system caret and assigns ownership of the caret to the specified window. The caret shape can be a line, a block, or a bitmap.

BOOL CreateCaret(

HWND  hWnd,	// handle of owner window
HBITMAP  hBitmap,	// handle of bitmap for caret shape
int  nWidth,	// caret width
int  nHeight	// caret height
);
Parameters

hWnd

Identifies the window that owns the caret.

hBitmap

Identifies the bitmap that defines the caret shape. If this parameter is NULL, the caret is solid. If this parameter is (HBITMAP) 1, the caret is gray. If this parameter is a bitmap handle, the caret is the specified bitmap. The bitmap handle must have been created by the CreateBitmap, CreateDIBitmap, or LoadBitmap function.

If hBitmap is a bitmap handle, CreateCaret ignores the nWidth and nHeight parameters; the bitmap defines its own width and height.

nWidth

Specifies the width of the caret in logical units. If this parameter is zero, the width is set to the system-defined window border width. If hBitmap is a bitmap handle, CreateCaret ignores this parameter.

nHeight

Specifies the height, in logical units, of the caret. If this parameter is zero, the height is set to the system-defined window border height. If hBitmap is a bitmap handle, CreateCaret ignores this parameter.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The nWidth and nHeight parameters specify the caret's width and height, in logical units; the exact width and height, in pixels, depend on the window's mapping mode.

CreateCaret automatically destroys the previous caret shape, if any, regardless of the window that owns the caret. The caret is hidden until the application calls the ShowCaret function to make the caret visible.

The caret is a shared resource; there is only one caret in the system. A window should create a caret only when it has the keyboard focus or is active. The window should destroy the caret before losing the keyboard focus or becoming inactive.

You can retrieve the width or height of the system's window border by using the GetSystemMetrics function, specifying the SM_CXBORDER and SM_CYBORDER values. Using the window border width or height guarantees that the caret will be visible on a high-resolution screen.

See Also

CreateBitmap, CreateDIBitmap, DestroyCaret, GetSystemMetrics, HideCaret, LoadBitmap, ShowCaret


CreateColorSpace  (preliminaryWindows 95)
CreateColorSpace  (preliminary−Windows 95)

The CreateColorSpace function creates a logical color space.

HCOLORSPACE CreateColorSpace(

LPLOGCOLORSPACE  lpLogColorSpace
);
Parameters

lpLogColorSpace

Pointer to the LOGCOLORSPACE structure.

Return Value

If the function succeeds, the return value is a handle that identifies a logical color space.

If the function fails, the return value is NULL.

See Also

LOGCOLORSPACE


CreateCompatibleBitmap

The CreateCompatibleBitmap function creates a bitmap compatible with the device that is associated with the specified device context.

HBITMAP CreateCompatibleBitmap(

HDC  hdc,	// handle of device context
int  nWidth,	// width of bitmap, in pixels
int  nHeight	// height of bitmap, in pixels
);
Parameters

hdc

Identifies a device context.

nWidth

Specifies the bitmap width, in pixels.

nHeight

Specifies the bitmap height, in pixels.

Return Value

If the function succeeds, the return value is a handle of the bitmap.

If the function fails, the return value is NULL.

Remarks

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 device context that is compatible with the original device.

Because memory device contexts allow both color and monochrome bitmaps, the format of the bitmap returned by the CreateCompatibleBitmap function differs when the specified device context is a memory device context. However, a compatible bitmap that was created for a nonmemory device context always possesses the same color format and uses the same color palette as the specified device context.

If an application sets the nWidth or nHeight parameters to zero, CreateCompatibleBitmap returns the handle of a 1- by 1-pixel, monochrome bitmap.

If a DIB section, which is a bitmap created by the CreateDIBSection function, is selected into the device context identified by the hdc parameter, the CreateCompatibleBitmap function creates a DIB section.

See Also

CreateDIBSection, DeleteObject, SelectObject


CreateCompatibleDC

The CreateCompatibleDC function creates a memory device context (DC) compatible with the specified device.

HDC CreateCompatibleDC(

HDC  hdc	// handle of memory device context
);
Parameters

hdc

Identifies the device context. If this handle is NULL, the function creates a memory device context compatible with the application's current screen.

Return Value

If the function succeeds, the return value is the handle of a memory device context.

If the function fails, the return value is NULL.

Remarks

Before an application can use a memory device context for drawing operations, it must select a bitmap of the correct width and height into the device context. Once a bitmap has been selected, the device context can be used to prepare images that will be copied to the screen or printed.

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 device context is no longer needed, an application must delete it by calling the DeleteDC function.

See Also

CreateCompatibleBitmap, DeleteDC, GetDeviceCaps


CreateConsoleScreenBuffer

The CreateConsoleScreenBuffer function creates a console screen buffer and returns a handle of it.

HANDLE CreateConsoleScreenBuffer(

DWORD  dwDesiredAccess,	// access flag
DWORD  dwShareMode,	// buffer share mode
LPSECURITY_ATTRIBUTES  *lpSecurityAttributes,	// address of security attributes
DWORD  dwFlags,	// type of buffer to create
LPVOID  lpScreenBufferData	// reserved
);
Parameters

dwDesiredAccess

Specifies the desired access to the console screen buffer. This parameter can be one or both of the following values:

Value	Meaning
GENERIC_READ	Requests read access to the console screen buffer, enabling the process to read data from the buffer.
GENERIC_WRITE	Requests write access to the console screen buffer, enabling the process to write data to the buffer.
dwShareMode

Specifies how this console screen buffer can be shared. This parameter can be zero, indicating that the buffer cannot be shared, or it can be one or both of the following two values:

Value	Meaning
FILE_SHARE_READ	Other open operations can be performed on the console screen buffer for read access.
FILE_SHARE_WRITE	Other open operations can be performed on the console screen buffer for write access.
*lpSecurityAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the console screen buffer.

dwFlags

Specifies the type of console screen buffer to create. The only currently supported screen buffer type is CONSOLE_TEXTMODE_BUFFER.

lpScreenBufferData

Reserved for possible future use; should be NULL.

Return Value

If the function succeeds, the return value is a handle of the new console screen buffer.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

A console can have multiple screen buffers but only one active screen buffer. Inactive screen buffers can be accessed for reading and writing, but only the active screen buffer is displayed. To make the new screen buffer the active screen buffer, use the SetConsoleActiveScreenBuffer function.

The calling process can use the returned handle in any function that requires a handle of a console screen buffer, subject to the limitations of access specified by the dwDesiredAccess parameter.

The calling process can use the DuplicateHandle function to create a duplicate screen buffer handle that has different access or inheritability from the original handle. However, DuplicateHandle cannot be used to create a duplicate that is valid for a different process (except through inheritance).

To close the screen buffer handle, use the CloseHandle function.

See Also

CloseHandle, DuplicateHandle, GetConsoleScreenBufferInfo, SECURITY_ATTRIBUTES, SetConsoleActiveScreenBuffer, SetConsoleScreenBufferSize


CreateCursor

The CreateCursor function creates a cursor having the specified size, bit patterns, and hot spot.

HCURSOR CreateCursor(

HINSTANCE  hInst,	// handle 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
);
Parameters

hInst

Identifies the current instance of the application creating the cursor.

xHotSpot

Specifies the horizontal position of the cursor's hot spot.

yHotSpot

Specifies the vertical position of the cursor's hot spot.

nWidth

Specifies the width, in pixels, of the cursor.

nHeight

Specifies the height, in pixels, of the cursor.

pvANDplane

Points to an array of bytes that contains the bit values for the AND bitmask of the cursor, as in a device-dependent monochrome bitmap.

pvXORplane

Points to an array of bytes that contains the bit values for the XOR bitmask of the cursor, as in a device-dependent monochrome bitmap.

Return Value

If the function succeeds, the return value identifies the cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The nWidth and nHeight parameters must specify a width and height that are supported by the current display driver, because the system cannot create cursors of other sizes. To determine the width and height supported by the display driver, use the GetSystemMetrics function, specifying the SM_CXCURSOR or SM_CYCURSOR value.

Before closing, an application must call the DestroyCursor function to free any system resources associated with the cursor.

See Also

CreateIcon, DestroyCursor, GetModuleHandle, GetSystemMetrics, SetCursor


CreateDC

The CreateDC function creates a device context (DC) for a device by using the specified name.

HDC CreateDC(

LPCTSTR  lpszDriver,	// address of string specifying driver name
LPCTSTR  lpszDevice,	// address of string specifying device name
LPCTSTR  lpszOutput,	// do not use; set to NULL
CONST DEVMODE  *lpInitData	// address of optional printer data
);
Parameters

lpszDriver

Applications written for earlier versions of Windows used this parameter to specify the filename (without extension) of the device driver. In Win32-based applications, this parameter is ignored and should be NULL, with one exception: You may obtain a display device context by specifying the null-terminated string "DISPLAY".

lpszDevice

Points to a null-terminated character string that specifies the name of the specific output device being used, as shown by the Print Manager (for example, "Epson FX-80"). It is not the printer model name. The lpszDevice parameter must be used.

lpszOutput

This parameter is ignored. Do not use it in a Win32 application. Win32-based applications should set this parameter to NULL. It exists to provide compatibility for applications written for earlier versions of Windows. For more information, see the following Remarks section.

lpInitData

Points to a DEVMODE structure containing device-specific initialization data for the device driver. The DocumentProperties function retrieves this structure filled in for a given device. The lpInitData parameter must be NULL if the device driver is to use the default initialization (if any) specified by the user.

Return Value

If the function succeeds, the return value is the handle of a device context for the specified device.

If the function fails, the return value is NULL.

Remarks

Applications written for earlier versions of Windows used the lpszOutput parameter to specify a port name or to print to a file. Win32-based applications do not need to specify a port name. Win32-based applications can print to a file by calling the StartDoc function with a DOCINFO structure whose lpszOutput member specifies the path of the output filename.

See Also

DEVMODE, DOCINFO, DocumentProperties, StartDoc


CreateDesktop  (preliminaryWindows NT)
CreateDesktop  (preliminary−Windows NT)

The CreateDesktop function creates a new desktop on the window station associated with the calling process. It returns a handle that can be used to access the new desktop. The calling process must have an associated window station, either assigned by the system at process creation time or set by SetProcessWindowStation. A desktop is a secure object contained within a window station object. A desktop has a logical display surface and contains windows, menus, and hooks.

HDESK CreateDesktop(

LPCTSTR lpscDesktop,	// name of the new desktop
LPCTSTR lpszDevice,	// name of display device to assign to the desktop
LPDEVMODE pDevMode,	// reserved; must be NULL
DWORD dwFlags,	// flags to control interaction with other applications
DWORD dwDesiredAccess,	// specifies access of returned handle
LPSECURITY_ATTRIBUTES lpsa	// specifies security attributes of the desktop
);
Parameters

lpscDesktop

Points to a null-terminated string specifying the name of the desktop to be created. Desktop names are case-insensitive and may not contain backslash characters (\).

lpszDevice

If specified, points to a null-terminated string specifying the name of the display device to assign to the desktop. The name must begin with a backslash character (\). If lpszDevice is NULL, the default display driver loaded at boot time is used.

pDevMode

Reserved; must be NULL.

dwFlags

A bit flag parameter that controls how the calling application will cooperate with other applications on the desktop. This parameter can specify zero or the following value:

Value	Description
DF_ALLOWOTHERACCOUNTHOOK	Allows processes running in other accounts on the desktop to set hooks in this process.
dwDesiredAccess

Specifies the type of access to the desktop. This parameter can be one or more of the following values:

Value	Description
DESKTOP_CREATEMENU	Required to create a menu on the desktop.
DESKTOP_CREATEWINDOW	Required to create a window on the desktop.
DESKTOP_ENUMERATE	Required for the desktop to be enumerated.
DESKTOP_HOOKCONTROL	Required to establish any of the window hooks.
DESKTOP_JOURNALPLAYBACK	Required to perform journal playback on the desktop.
DESKTOP_JOURNALRECORD	Required to perform journal recording on the desktop.
DESKTOP_READOBJECTS	Required to read objects on the desktop.
DESKTOP_SWITCHDESKTOP	Required to activate the desktop using the SwitchDesktop function.
DESKTOP_WRITEOBJECTS	Required to write objects on the desktop.
lpsa

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the desktop.

If either lpsa or lpsa->lpSecurityDescriptor is NULL, the desktop inherits its security descriptor from the parent window station, and the resulting handle is not inheritable.

Return Value

If the function succeeds, the return value is a handle of the newly created desktop.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CreateDesktop function returns a handle that can be used to access the desktop.

See Also

SECURITY_ATTRIBUTES, SetProcessWindowStation, SwitchDesktop


CreateDialog

The CreateDialog function creates a modeless dialog box from a dialog box template resource.

HWND CreateDialog(

HINSTANCE  hInstance,	// handle of application instance
LPCTSTR  lpTemplate,	// identifies dialog box template name
HWND  hWndParent,	// handle of owner window
DLGPROC  lpDialogFunc	// address of dialog box procedure
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the dialog box template.

lpTemplate

Identifies the dialog box template. This parameter is either the 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.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

Return Value

If the function succeeds, the return value is the handle of the dialog box.

If the function fails, the return value is NULL.

Remarks

The CreateDialog function uses the CreateWindowEx function to create the dialog box. CreateDialog then sends a WM_INITDIALOG message (and a WM_SETFONT message if the template specifies the DS_SETFONT style) to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialog returns the window handle 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

The CreateDialogIndirect function creates a modeless dialog box from a dialog box template in memory.

HWND CreateDialogIndirect(

HINSTANCE  hInstance,	// handle of application instance
LPCDLGTEMPLATE  lpName,	// address of dialog box template
HWND  hWndParent,	// handle of owner window
DLGPROC  lpDialogFunc	// address of dialog box procedure
);
Parameters

hInstance

Identifies the instance of the module that creates the dialog box.

lpName

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.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

Return Value

If the function succeeds, the return value is the window handle of the dialog box.

If the function fails, the return value is NULL.

Remarks

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, DLGITEMTEMPLATE, DLGTEMPLATE, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDialogIndirectParam

The CreateDialogIndirectParam function creates a modeless dialog box from a dialog box template in memory. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

HWND CreateDialogIndirectParam(

HINSTANCE  hInstance,	// handle of application instance
LPCDLGTEMPLATE  lpTemplate,	// address of dialog box template
HWND  hWndParent,	// handle of owner window
DLGPROC  lpDialogFunc,	// address of dialog box procedure
LPARAM  lParamInit	// initialization value
);
Parameters

hInstance

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.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see DialogProc.

lParamInit

Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Value

If the function succeeds, the return value is the window handle of the dialog box.

If the function fails, the return value is NULL.

Remarks

The CreateDialogIndirectParam function uses the CreateWindowEx function to create the dialog box. CreateDialogIndirectParam then sends a WM_INITDIALOG message (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, DLGITEMTEMPLATE, DLGTEMPLATE, DialogProc, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDialogParam

The CreateDialogParam function creates a modeless dialog box from a dialog box template resource. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

HWND CreateDialogParam(

HINSTANCE  hInstance,	// handle of application instance
LPCTSTR  lpTemplateName,	// identifies dialog box template
HWND  hWndParent,	// handle of owner window
DLGPROC  lpDialogFunc,	// address of dialog box procedure
LPARAM  dwInitParam	// initialization value
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the dialog box template.

lpTemplateName

Identifies the dialog box template. This parameter is either the 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.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see DialogProc .

dwInitParam

Specifies the value to pass to the dialog box procedure in the lParam parameter in the WM_INITDIALOG message.

Return Value

If the function succeeds, the return value is the window handle of the dialog box.

If the function fails, the return value is NULL.

Remarks

The CreateDialogParam function uses the CreateWindowEx function to create the dialog box. CreateDialogParam then sends a WM_INITDIALOG message (and a WM_SETFONT message if the template specifies the DS_SETFONT style) to the dialog box procedure. The function displays the dialog box if the template specifies the WS_VISIBLE style. Finally, CreateDialogParam returns the window handle of the dialog box.

After CreateDialogParam returns, the application displays the dialog box (if it is not already displayed) by using the ShowWindow function. The application destroys the dialog box by using the DestroyWindow function.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, CreateWindowEx, DestroyWindow, DialogProc, MAKEINTRESOURCE, ShowWindow, WM_INITDIALOG, WM_SETFONT


CreateDIBitmap

The CreateDIBitmap function creates a device-dependent bitmap (DDB) from a device-independent bitmap (DIB) and, optionally, sets the bitmap bits.

HBITMAP CreateDIBitmap(

HDC  hdc,	// handle 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
);
Parameters

hdc

Identifies a device context.

lpbmih

Points to a BITMAPINFOHEADER structure.

If fdwInit is CBM_INIT, the function uses the BITMAPINFOHEADER structure to obtain the desired width and height of the bitmap as well as other information. Note that a positive value for the height indicates a bottom-up DIB while a negative value for the height indicates a top-down DIB. This scenario is compatible with the CreateDIBitmap function.

fdwInit

A set of bit flags that specify how the operating system initializes the bitmap's bits.

The following bit flag constant is defined:

Value	Meaning
CBM_INIT	If this flag is set, the operating system uses the data pointed to by the lpbInit and lpbmi parameters to initialize the bitmap's bits. If this flag is clear, the data pointed to by those parameters is not used.
If fdwInit is zero, the operating system does not initialize the bitmap's bits.

lpbInit

Points to an array of bytes containing the initial bitmap data. The format of the data depends on the biBitCount member of the BITMAPINFO structure to which the lpbmi parameter points.

lpbmi

Points to a BITMAPINFO structure that describes the dimensions and color format of the array pointed to by the lpbInit parameter.

fuUsage

Specifies whether the bmiColors member of the BITMAPINFO structure was initialized and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or palette indices. The fuUsage parameter must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	A color table is provided and consists of an array of 16-bit indices into the logical palette of the device context into which the bitmap is to be selected.
DIB_RGB_COLORS	A color table is provided and contains literal RGB values.
Return Value

If the function succeeds, the return value is a handle of the bitmap.

If the function fails, the return value is NULL.

Remarks

The CBM_CREATDIB flag for the fdwInit parameter is no longer supported.

See Also

BITMAPINFOHEADER, BITMAPINFO, DeleteObject, GetDeviceCaps, GetSystemPaletteEntries, SelectObject


CreateDIBPatternBrush

The CreateDIBPatternBrush function creates a logical brush that has the pattern specified by the specified device-independent bitmap (DIB). The brush can subsequently be selected into any device context that is associated with a device that supports raster operations.

This function is provided only for compatibility with applications written for versions of Windows earlier than 3.0. For Win32-based applications, use the CreateDIBPatternBrushPt function.

HBRUSH CreateDIBPatternBrush(

HGLOBAL  hglbDIBPacked,	// handle of device-independent bitmap
UINT  fuColorSpec	// color table data
);
Parameters

hglbDIBPacked

Identifies a global memory object containing a packed DIB, which consists of a BITMAPINFO structure immediately followed by an array of bytes defining the pixels of the bitmap.

fuColorSpec

Specifies whether the bmiColors member of the BITMAPINFO structure is initialized and, if so, whether this member contains explicit red, green, blue (RGB) values or indices into a logical palette. The fuColorSpec parameter must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	A color table is provided and consists of an array of 16-bit indices into the logical palette of the device context into which the brush is to be selected.
DIB_RGB_COLORS	A color table is provided and contains literal RGB values.
Return Value

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

When an application selects a two-color DIB pattern brush into a monochrome device context, Windows does not acknowledge the colors specified in the DIB; instead, it displays the pattern brush using the current background and foreground colors of the device context. Pixels mapped to the first color of the DIB (offset 0 in the DIB color table) are displayed using the foreground color; pixels mapped to the second color (offset 1 in the color table) are displayed using the background color.

See Also

BITMAPINFO, CreateDIBPatternBrushPt, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, SetBkColor, SetTextColor


CreateDIBPatternBrushPt

The CreateDIBPatternBrushPt function creates a logical brush that has the pattern specified by the device-independent bitmap (DIB).

HBRUSH CreateDIBPatternBrushPt(

CONST VOID *  lpPackedDIB,	// address of structure and bitmap bits
UINT  iUsage	// usage flags
);
Parameters

lpPackedDIB

Points to a packed DIB consisting of a BITMAPINFO structure immediately followed by an array of bytes defining the pixels of the bitmap.

iUsage

Specifies whether the bmiColors member of the BITMAPINFO structure contains a valid color table and, if so, whether the entries in this color table contain explicit red, green, blue (RGB) values or palette indices. The iUsage parameter must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	A color table is provided and consists of an array of 16-bit indices into the logical palette of the device context into which the brush is to be selected.
DIB_RGB_COLORS	A color table is provided and contains literal RGB values.
Return Value

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

A brush is a bitmap that Windows uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreateDIBPatternBrushPt, it can select that brush into any device context by calling the SelectObject function.

See Also

BITMAPINFO, CreateDIBPatternBrush, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, DeleteObject, GetBrushOrgEx, SelectObject, SetBrushOrgEx


CreateDIBSection

The CreateDIBSection function creates a device-independent bitmap (DIB) that applications can write to directly. The function gives you a pointer to the location of the bitmap's bit values. You can supply a handle to a file mapping object that the function will use to create the bitmap, or you can let the operating system allocate the memory for the bitmap.

HBITMAP CreateDIBSection(

HDC hdc,	// handle of device context
CONST BITMAPINFO *pbmi,	// address of structure containing bitmap size, format, and color data
UINT iUsage,	// color data type indicator: RGB values or palette indices
VOID **ppvBits,	// pointer to variable to receive a pointer to the bitmap's bit values
HANDLE hSection,	// optional handle to a file mapping object
DWORD dwOffset	// offset to the bitmap bit values within the file mapping object
);
Parameters

hdc

Handle to a device context. If the value of iUsage is DIB_PAL_COLORS, the function uses this device context's logical palette to initialize the device-independent bitmap's colors.

pbmi

Points to a BITMAPINFO structure that specifies various attributes of the device-independent bitmap, including the bitmap's dimensions and colors.

iUsage

Specifies the type of data contained in the bmiColors array member of the BITMAPINFO structure pointed to by pbmi: logical palette indices or literal RGB values. The following values are defined:

Value	Meaning
DIB_PAL_COLORS	The bmiColors member is an array of 16-bit indices into the logical palette of the device context specified by hdc.
DIB_RGB_COLORS	The BITMAPINFO structure contains an array of literal RGB values.
ppvBits

Points to a variable that receives a pointer to the location of the device-independent bitmap's bit values.

hSection

Handle to a file mapping object that the function will use to create the device-independent bitmap. This parameter can be NULL.

If hSection is not NULL, it must be a handle to a file mapping object created by calling the CreateFileMapping function. Handles created by other means will cause CreateDIBSection to fail.

If hSection is not NULL, the CreateDIBSection function locates the bitmap's bit values at offset dwOffset in the file mapping object referred to by hSection. An application can later retrieve the hSection handle by calling the GetObject function with the HBITMAP returned by CreateDIBSection.

If hSection is NULL, the operating system allocates memory for the device-independent bitmap. In this case, the CreateDIBSection function ignores the dwOffset parameter. An application cannot later obtain a handle to this memory: the dshSection member of the DIBSECTION structure filled in by calling the GetObject function will be NULL.

dwOffset

Specifies the offset from the beginning of the file mapping object referenced by hSection where storage for the bitmap's bit values is to begin. This value is ignored if hSection is NULL. The bitmap's bit values are aligned on doubleword boundaries, so dwOffset must be a multiple of the size of a DWORD.

Return Value

If the function succeeds, the return value is a handle to the newly created device-independent bitmap, and *ppvBits points to the bitmap's bit values.

If the function fails, the return value is NULL, and *ppvBits is NULL. To get extended error information, call GetLastError.

Remarks

As noted above, if hSection is NULL, the operating system allocates memory for the device-independent bitmap. The operating system closes the handle to that memory when you later delete the device-independent bitmap by calling the DeleteObject function. If hSection is not NULL, you must close the hSection memory handle yourself after calling DeleteObject to delete the bitmap.

Windows NT: You need to guarantee that the GDI subsystem has completed any drawing to a bitmap created by CreateDIBSection before you draw to the bitmap yourself. Access to the bitmap must be synchronized. Do this by calling the GdiFlush function. This applies to any use of the pointer to the bitmap's bit values, including passing the pointer in calls to functions such as SetDIBits.

See Also

BITMAPINFO, CreateFileMapping, DeleteObject, DIBSECTION, GetDIBColorTable, GetObject, GdiFlush, HBITMAP, SetDIBits SetDIBColorTable


CreateDirectory

The CreateDirectory function creates a new directory. If the underlying file system supports security on files and directories, the function applies a specified security descriptor to the new directory. Note that CreateDirectory does not have a template parameter, while CreateDirectoryEx does.

BOOL CreateDirectory(

LPCTSTR  lpPathName,	// pointer to a directory path string
LPSECURITY_ATTRIBUTES  lpSecurityAttributes	// pointer to a security descriptor
);
Parameters

lpPathName

Points to a null-terminated string that specifies the path of the directory to be created.

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the CreateDirectory function parses paths.

Windows NT: An application can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) version of CreateDirectory and prepending "\\?\" to the path. The "\\?\" tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with CreateDirectoryW. This also works with UNC names. The "\\?\" is ignored as part of the path. For example, "\\?\C:\myworld\private" is seen as "C:\myworld\private", and "\\?\UNC\bill_g_1\hotstuff\coolapps" is seen as "\\bill_g_1\hotstuff\coolapps".

lpSecurityAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the directory to be created. The file system must support this parameter for it to have an effect.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Windows NT

Some file systems, such as NTFS, support compression for individual files and directories. On volumes formatted for such a file system, a new directory inherits the compression attribute of its parent directory.

An application can obtain a handle to a directory by calling CreateFile with the FILE_FLAG_BACKUP_SEMANTICS flag set. For a code example, see CreateFile.

See Also

CreateDirectoryEx, CreateFile, RemoveDirectory, SECURITY_ATTRIBUTES


CreateDirectoryEx

The CreateDirectoryEx function creates a new directory with a specified path that retains the attributes of a specified template directory. If the underlying file system supports security on files and directories, the function applies a specified security descriptor to the new directory. The new directory retains the other attributes of the specified template directory. Note that CreateDirectoryEx has a template parameter, while CreateDirectory does not.

BOOL CreateDirectoryEx(

LPCTSTR  lpTemplateDirectory,	// pointer to path string of template directory
LPCTSTR  lpNewDirectory,	// pointer to path string of directory to create
LPSECURITY_ATTRIBUTES  lpSecurityAttributes	// pointer to security descriptor
);
Parameters

lpTemplateDirectory

Points to a null-terminated string that specifies the path of the directory to use as a template when creating the new directory.

lpNewDirectory

Points to a null-terminated string that specifies the path of the directory to be created.

lpSecurityAttributes

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The CreateDirectoryEx function allows you to create directories that inherit stream information from other directories. This function is useful, for example, when dealing with Macintosh directories, which have a resource stream that is needed to properly identify directory contents as an attribute.

Windows NT

Some file systems, such as NTFS, support compression for individual files and directories. On volumes formatted for such a file system, a new directory inherits the compression attribute of its parent directory.

You can obtain a handle to a directory by calling CreateFile with the FILE_FLAG_BACKUP_SEMANTICS flag set. See CreateFile for a code example.

See Also

CreateDirectory, CreateFile, RemoveDirectory, SECURITY_ATTRIBUTES


CreateDiscardableBitmap

The CreateDiscardableBitmap function creates a discardable bitmap that is compatible with the specified device. The bitmap has the same bits-per-pixel format and the same color palette as the device. An application can select this bitmap as the current bitmap for a memory device that is compatible with the specified device.

The CreateDiscardableBitmap function is included only for compatibility with earlier versions of Windows. For Win32-based applications, use the CreateCompatibleBitmap function.

HBITMAP CreateDiscardableBitmap(

HDC  hdc,	// handle of device context
int  nWidth,	// bitmap width
int  nHeight	// bitmap height
);
Parameters

hdc

Identifies a device context.

nWidth

Specifies the width, in bits, of the bitmap.

nHeight

Specifies the height, in bits, of the bitmap.

Return Value

If the function succeeds, the return value is a handle of the bitmap.

If the function fails, the return value is NULL.

See Also

CreateCompatibleBitmap


CreateEllipticRgn

The CreateEllipticRgn function creates an elliptical region.

HRGN CreateEllipticRgn(

int  nLeftRect,	// x-coordinate of the upper-left corner of the bounding rectangle
int  nTopRect,	// y-coordinate of the upper-left corner of the bounding rectangle
int  nRightRect,	// x-coordinate of the lower-right corner of the bounding rectangle
int  nBottomRect	// y-coordinate of the lower-right corner of the bounding rectangle
);
Parameters

nLeftRect

Specifies the x-coordinate of the upper-left corner of the bounding rectangle of the ellipse.

nTopRect

Specifies the y-coordinate of the upper-left corner of the bounding rectangle of the ellipse.

nRightRect

Specifies the x-coordinate of the lower-right corner of the bounding rectangle of the ellipse.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the bounding rectangle of the ellipse.

Return Value

If the function succeeds, the return value is the handle of the region.

If the function fails, the return value is NULL.

Remarks

A bounding rectangle defines the size, shape, and orientation of the region: The long sides of the rectangle define the length of the ellipse's major axis; the short sides define the length of the ellipse's minor axis; and the center of the rectangle defines the intersection of the major and minor axes.

The coordinates of the bounding rectangle are specified in logical units.

See Also

CreateEllipticRgnIndirect, DeleteObject, SelectObject


CreateEllipticRgnIndirect

The CreateEllipticRgnIndirect function creates an elliptical region.

HRGN CreateEllipticRgnIndirect(

CONST RECT  *lprc	// address of structure defining bounding rectangle
);
Parameters

lprc

Points to a RECT structure that contains the coordinates of the upper-left and lower-right corners of the bounding rectangle of the ellipse.

Return Value

If the function succeeds, the return value is the handle of the region.

If the function fails, the return value is NULL.

Remarks

A bounding rectangle defines the size, shape, and orientation of the region: The long sides of the rectangle define the length of the ellipse's major axis; the short sides define the length of the ellipse's minor axis; and the center of the rectangle defines the intersection of the major and minor axes.

The coordinates of the bounding rectangle are specified in logical units.

See Also

CreateEllipticRgn, DeleteObject, RECT, SelectObject


CreateEnhMetaFile

The CreateEnhMetaFile function creates a device context for an enhanced-format metafile. This device context can be used to store a device-independent picture.

HDC CreateEnhMetaFile(

HDC  hdcRef,	// handle 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
);
Parameters

hdcRef

Identifies a reference device for the enhanced metafile.

lpFilename

Points to the filename for the enhanced metafile to be created. If this parameter is NULL, the enhanced metafile is memory based and its contents are lost when it is deleted by using the DeleteEnhMetaFile function.

lpRect

Points to a RECT structure that specifies the dimensions (in .01-millimeter units) of the picture to be stored in the enhanced metafile.

lpDescription

Points to a string that specifies the name of the application that created the picture, as well as the picture's title.

Return Value

If the function succeeds, the return value is a handle of the device context for the enhanced metafile.

If the function fails, the return value is NULL.

Remarks

Where text arguments must use Unicode characters, use 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 device context created by this function to store a graphics picture in an enhanced metafile. The handle identifying this device context can be passed to any GDI function.

After an application stores a picture in an enhanced metafile, it can display the picture on any output device by calling the PlayEnhMetaFile function. When displaying the picture, Windows uses the rectangle pointed to by the lpRect parameter and the resolution data from the reference device to position and scale the picture.

The device context returned by this function contains the same default attributes associated with any new device context.

Applications must use the GetWinMetaFileBits function to convert an enhanced metafile to the older Windows metafile format.

The filename for the enhanced metafile should use the .EMF extension.

See Also

CloseEnhMetaFile, DeleteEnhMetaFile, GetEnhMetaFileDescription, GetEnhMetaFileHeader, GetWinMetaFileBits, PlayEnhMetaFile, RECT


 CreateEvent

The CreateEvent function creates a named or unnamed event object.

HANDLE CreateEvent(

LPSECURITY_ATTRIBUTES  lpEventAttributes,	// address of security attributes
BOOL  bManualReset,	// flag for manual-reset event
BOOL  bInitialState,	// flag for initial state
LPCTSTR  lpName	// address of event-object name
);
Parameters

lpEventAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the event object.

If lpEventAttributes is NULL, the event object is created with a default security descriptor and the resulting handle is not inheritable.

bManualReset

Specifies whether a manual-reset or auto-reset event object is created. If TRUE, then you must use the ResetEvent function to manually reset the state to nonsignaled. If FALSE, Windows automatically resets the state to nonsignaled after a single waiting thread has been released.

bInitialState

Specifies the initial state of the event object. If TRUE, the initial state is signaled; otherwise, it is nonsignaled.

lpName

Points to a null-terminated string specifying the name of the event object. The name is limited to MAX_PATH characters and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive.

If lpName matches the name of an existing named event object, this function requests EVENT_ALL_ACCESS access to the existing object. In this case, the bManualReset and bInitialState parameters are ignored because they have already been set by the creating process. If the lpEventAttributes parameter is not NULL, it determines whether the handle can be inherited, but its security-descriptor member is ignored.

If lpName is NULL, the event object is created without a name.

If lpName matches the name of an existing semaphore, mutex, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because event, mutex, semaphore, and file-mapping objects share the same name space.

Return Value

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, call GetLastError.

Remarks

The handle returned by CreateEvent has EVENT_ALL_ACCESS access to the new event object and can be used in any function that requires a handle 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 bInitialState parameter. Use the SetEvent function to set the state of an event object to signaled. Use the ResetEvent function to reset the state of an event object to nonsignaled.

When the state of a manual-reset event object is signaled, it remains signaled until it is explicitly reset to nonsignaled by the ResetEvent function. Any number of waiting threads, or threads that subsequently begin wait operations for the specified event object, can be released while the object's state is signaled.

When the state of an auto-reset event object is signaled, it remains signaled until a single waiting thread is released; the system then automatically resets the state to nonsignaled. If no threads are waiting, the event object's state remains signaled.

Multiple processes can have handles of the same event object, enabling use of the object for interprocess synchronization. The following object-sharing mechanisms are available:

•	A child process created by the CreateProcess function can inherit a handle of an event object if the lpEventAttributes parameter of CreateEvent enabled inheritance.

•	A process can specify the event-object handle in a call to the DuplicateHandle function to create a duplicate handle that can be used by another process.

•	A process can specify the name of an event object in a call to the OpenEvent or CreateEvent function.

Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The event object is destroyed when its last handle has been closed.

See Also

CloseHandle, CreateProcess, DuplicateHandle, MsgWaitForMultipleObjects, OpenEvent, ResetEvent, SECURITY_ATTRIBUTES, SetEvent, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


 CreateFile

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. It can also open and return a handle to a directory.

HANDLE CreateFile(

LPCTSTR  lpFileName,	// address of name of the file
DWORD  dwDesiredAccess,	// access (read-write) mode
DWORD  dwShareMode,	// share mode
LPSECURITY_ATTRIBUTES  lpSecurityAttributes,	// address of security descriptor
DWORD  dwCreationDistribution,	// how to create
DWORD  dwFlagsAndAttributes,	// file attributes
HANDLE  hTemplateFile	// handle of file with attributes to copy
);
Parameters

lpFileName

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.

If *lpFileName is a path, there is a default string size limit of MAX_PATH characters. This limit is related to how the CreateFile function parses paths.

Windows NT: You can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) version of CreateFile and prepending "\\?\" to the path. The "\\?\" tells the function to turn off path parsing. This lets you use paths that are nearly 32k Unicode characters long. You must use fully-qualified paths with this technique. This also works with UNC names. The "\\?\" is ignored as part of the path. For example, "\\?\C:\myworld\private" is seen as "C:\myworld\private", and "\\?\UNC\tom_1\hotstuff\coolapps" is seen as "\\tom_1\hotstuff\coolapps".

dwDesiredAccess

Specifies the type of access to the file or other object. An application can obtain read access, write access, read-write access, or device query access. You can use the following flag constants to build a value for this parameter. Both GENERIC_READ and GENERIC_WRITE must be set to obtain read-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.
dwShareMode

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. If the CreateFile function is opening the client end of a mailslot, this flag is specified.
FILE_SHARE_WRITE	Other open operations can be performed on the file for write access.
lpSecurityAttributes

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.

dwCreationDistribution

Specifies which action to take on files that exist, and which action to take when files do not exist. For more information about this parameter, see the following Remarks section. This parameter must be one of the following values:

Value	Meaning
CREATE_NEW	Creates a new file. The function fails if the specified file already exists.
CREATE_ALWAYS	Creates a new file. The function overwrites the file if it exists.
OPEN_EXISTING	Opens the file. The function fails if the file does not exist.
	See the "Remarks" section, following, for a discussion of why you should use the OPEN_EXISTING flag if you are using the CreateFile function for 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 dwCreationDistribution were CREATE_NEW.
TRUNCATE_EXISTING	Opens the file. Once opened, the file is truncated so that its size is zero bytes. The calling process must open the file with at least GENERIC_WRITE access. The function fails if the file does not exist.
dwFlagsAndAttributes

Specifies the file attributes and flags for the file.

Any combination of the following attributes is acceptable, except all other file attributes override FILE_ATTRIBUTE_NORMAL.

Attribute	Meaning
FILE_ATTRIBUTE_ARCHIVE	The file is an archive file. Applications use this attribute 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.
Any combination of the following flags is acceptable.

Flag	Meaning
FILE_FLAG_WRITE_THROUGH
	Instructs the operating system to write through any intermediate cache and go directly to the file. The operating system can still cache write operations, but cannot lazily flush them.
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 you specify FILE_FLAG_OVERLAPPED, the ReadFile and WriteFile functions must specify an OVERLAPPED structure. That is, when FILE_FLAG_OVERLAPPED is specified, an application must perform overlapped reading and writing.
	When FILE_FLAG_OVERLAPPED is specified, the operating system does not maintain the file pointer. The file position must be passed as part of the lpOverlapped parameter (pointing to an OVERLAPPED structure) to the ReadFile and WriteFile functions.
	This flag also enables more than one operation to be performed simultaneously with the handle (a simultaneous read and write operation, for example).
FILE_FLAG_NO_BUFFERING
	Instructs the operating system to open the file with no intermediate buffering or caching. This can provide performance gains in some situations.  An application must meet certain requirements when working with files opened with FILE_FLAG_NO_BUFFERING: • File access must begin at offsets within the file that are integer multiples of the volume's sector size.  • File access must be for numbers of bytes that are integer multiples of the volume's sector size. For example, if the sector size is 512 bytes, an application can request reads and writes of 512, 1024, or 2048 bytes, but not of 335, 981, or 7171 bytes.  • Buffer addresses for read and write operations must be aligned on addresses in memory that are integer multiples of the volume's sector size.  An application can determine a volume's sector size by calling the GetDiskFreeSpace function.
FILE_FLAG_RANDOM_ACCESS
	Indicates that the file is accessed randomly. Windows 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 large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes.
FILE_FLAG_DELETE_ON_CLOSE
	Indicates that the operating system is to delete the file immediately after all its handles have been closed.
FILE_FLAG_BACKUP_SEMANTICS
	Windows NT only: Indicates that the file is being opened or created for a backup or restore operation. The operating system ensures that the calling process overrides file security checks, provided it has the necessary permission to do so. The relevant permissions are SE_BACKUP_NAME and SE_RESTORE_NAME. A Windows NT application can also set this flag to obtain a handle to a directory. A directory handle can be passed to some Win32 functions in place of a file handle.
FILE_FLAG_POSIX_SEMANTICS
	Indicates that the file is to be accessed according to POSIX rules. This includes allowing multiple files with names, differing only in case, for file systems that support such naming. Use care when using this option because files created with this flag may not be accessible by applications written for MS-DOS, Windows 3.x, or Windows NT.
If the CreateFile function opens the client side of a named pipe, the dwFlagsAndAttributes parameter can also contain Security Quality of Service information. When the calling application specifies the SECURITY_SQOS_PRESENT flag, the dwFlagsAndAttributes parameter can contain one or more of the following values:

Value	Meaning
SECURITY_ANONYMOUS	Specifies to impersonate the client at the Anonymous impersonation level.
SECURITY_IDENTIFICATION	Specifies to impersonate the client at the Identification impersonation level.
SECURITY_IMPERSONATION	Specifies to impersonate the client at the Impersonation impersonation level.
SECURITY_DELEGATION	Specifies to impersonate the client at the Delegation impersonation level.
SECURITY_CONTEXT_TRACKING	Specifies that the security tracking mode is dynamic. If this flag is not specified, Security Tracking Mode is static.
SECURITY_EFFECTIVE_ONLY	Specifies that only the enabled aspects of the client's security context are available to the server. If you do not specify this flag, all aspects of the client's security context are available. This flag allows the client to limit the groups and privileges that a server can use while impersonating the client.
hTemplateFile

Specifies a handle with GENERIC_READ access to a template file. The template file supplies extended attributes for the file being created.

Return Value

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 dwCreationDistribution is CREATE_ALWAYS or OPEN_ALWAYS, a call to GetLastError returns ERROR_ALREADY_EXISTS (even though the function has succeeded). If the file does not exist before the call, GetLastError returns zero.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

When creating a new file, the CreateFile function performs the following actions:

•	Combines the file attributes and flags specified by dwFlagsAndAttributes with FILE_ATTRIBUTE_ARCHIVE.

•	Sets the file length to zero.

•	Copies the extended attributes supplied by the template file to the new file if the hTemplateFile parameter is specified.

When opening an existing file, CreateFile performs the following actions:

•	Combines the file flags specified by dwFlagsAndAttributes with existing file attributes. CreateFile ignores the file attributes specified by dwFlagsAndAttributes.

•	Sets the file length according to the value of dwCreationDistribution.

•	Ignores the hTemplateFile parameter.

•	Ignores the lpSecurityDescriptor member of the SECURITY_ATTRIBUTES structure if the lpSecurityAttributes parameter is not NULL. The other structure members are 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 dwOpenMode parameter of the CreateNamedPipe function. 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 dwCreationDistribution parameter must be OPEN_EXISTING, and the hTemplate parameter must be NULL. Read, write, or read-write access can be specified, and the handle can be opened for overlapped I/O.

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
lpFileName	Use the CONIN$ value to specify console input and the CONOUT$ value to specify console output.
	CONIN$ gets a handle of the console's input buffer, even if the SetStdHandle function redirected the standard input handle. To get the standard input handle, use the GetStdHandle function.
	CONOUT$ gets a handle of the active screen buffer, even if SetStdHandle redirected the standard output handle. To get the standard output handle, use GetStdHandle.
dwDesiredAccess	GENERIC_READ | GENERIC_WRITE is preferred, but either one can limit access.
dwShareMode	If the calling process inherited the console or if a child process should be able to access the console, this parameter must be FILE_SHARE_READ | FILE_SHARE_WRITE.
lpSecurityAttributes	If you want the console to be inherited, the bInheritHandle member of the SECURITY_ATTRIBUTES structure must be TRUE.
dwCreationDistribution	The user should specify OPEN_EXISTING when using CreateFile to open the console.
dwFlagsAndAttributes	Ignored.
hTemplateFile	Ignored.
The following list shows the effects of various settings of fwdAccess and lpFileName.

lpFileName	fwdAccess	Result
CON	GENERIC_READ	Opens console for input.
CON	GENERIC_WRITE	Opens console for output.
CON	GENERIC_READ\ GENERIC_WRITE	Causes CreateFile to fail, returning an error of ERROR_PATH_NOT_FOUND.
You can use the CreateFile function to open a disk drive or a partition on a disk drive. The function returns a handle to the disk device; that handle can be used with the DeviceIOControl function. The following requirements must be met in order for such a call to succeed:

•	The caller must have administrative privileges for the operation to succeed on a hard disk drive.

•	The lpFileName string should be of the form \\.\PHYSICALDRIVEx to open the hard disk x. Hard disk numbers start at zero. For example:

String	Meaning
\\.\PHYSICALDRIVE2	Obtains a handle to the third physical drive on the user's computer.
•	The lpFileName string should be \\.\x: to open a floppy drive x or a partition x on a hard disk. For example:

String	Meaning
\\.\A:	Obtains a handle to drive A on the user's computer.
\\.\C:	Obtains a handle to drive C on the user's computer.
Windows 95: This technique does not work for opening a logical drive. In Windows 95, specifying a string in this form causes CreateFile to return an error.

•	The dwCreationDistribution parameter must have the OPEN_EXISTING value.

•	When opening a floppy disk or a partition on a hard disk, you must set the FILE_SHARE_WRITE flag in the dwShareMode parameter.

The CloseHandle function is used to close a handle returned by CreateFile.

As noted above, specifying zero for dwDesiredAccess allows an application to query device attributes without actually accessing the device. This type of querying is useful, for example, if an application wants to determine the size of a floppy disk drive and the formats it supports without having a floppy in the drive.

As previously noted, if an application opens a file with FILE_FLAG_NO_BUFFERING set, buffer addresses for read and write operations must be aligned on memory addresses that are integer multiples of the volume's sector size. One way to do this is to use VirtualAlloc to allocate the buffer. The VirtualAlloc function allocates memory that is aligned on addresses that are integer multiples of the operating system's memory page size. Since both memory page and volume sector sizes are powers of 2, and memory pages are larger than volume sectors, this memory is also aligned on addresses that are integer multiples of a volume's sector size.

An application cannot create a directory with CreateFile; it must call CreateDirectory or CreateDirectoryEx to create a directory.

Windows NT:

You can obtain a handle to a directory by setting the FILE_FLAG_BACKUP_SEMANTICS flag. A directory handle can be passed to some Win32 functions in place of a file handle.

Some file systems, such as NTFS, support compression for individual files and directories. On volumes formatted for such a file system, a new directory inherits the compression attribute of its parent directory.

See Also

AllocConsole, CloseHandle, ConnectNamedPipe, CreateDirectory, CreateDirectoryEx, CreateNamedPipe, DeviceIOControl, GetDiskFreeSpace, GetOverlappedResult, GetStdHandle, OpenFile, OVERLAPPED, ReadFile, SECURITY_ATTRIBUTES, SetStdHandle TransactNamedPipe, VirtualAlloc, WriteFile


 CreateFileMapping

The CreateFileMapping function creates a named or unnamed file-mapping object for the specified file.

HANDLE CreateFileMapping(

HANDLE  hFile,	// handle of file to map
LPSECURITY_ATTRIBUTES  lpFileMappingAttributes,	// optional security attributes
DWORD  flProtect,	// protection for mapping object
DWORD  dwMaximumSizeHigh,	// high-order 32 bits of object size
DWORD  dwMaximumSizeLow,	// low-order 32 bits of object size
LPCTSTR  lpName	// name of file-mapping object
);
Parameters

hFile

Identifies the file from which to create a mapping object. The file must be opened with an access mode compatible with the protection flags specified by the flProtect parameter. It is recommended, though not required, that files you intend to map be opened for exclusive access.

If hFile is (HANDLE)0xFFFFFFFF, the calling process must also specify a mapping object size in the dwMaximumSizeHigh and dwMaximumSizeLow parameters. The function creates a file-mapping object of the specified size backed by the operating-system paging file rather than by a named file in the file system. The file-mapping object can be shared through duplication, through inheritance, or by name.

lpFileMappingAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the mapping object.

If lpFileMappingAttributes is NULL, the file-mapping object is created with a default security descriptor and the resulting handle is not inherited.

flProtect

Specifies the protection desired for the file view, when the file is mapped. This parameter can be one of the following values:

Value	Description
PAGE_READONLY	Gives read-only access to the committed region of pages. An attempt to write to or execute the committed region results in an access violation. The file specified by the hFile parameter must have been created with GENERIC_READ access.
PAGE_READWRITE	Gives read-write access to the committed region of pages. The file specified by hFile must have been created with GENERIC_READ and GENERIC_WRITE access.
PAGE_WRITECOPY	Gives copy on write access to the committed region of pages. The files specified by the hFile parameter must have been created with GENERIC_READ and GENERIC_WRITE access.
In addition, an application can specify certain section attributes by combining (using the bitwise OR operator) one or more of the following section attribute values with one of the preceding page protection values:

Value	Description
SEC_COMMIT	Allocates physical storage in memory or in the paging file on disk for all pages of a section. This is the default setting.
SEC_IMAGE	The file specified for a section's file mapping is an executable image file. Because the mapping information and file protection are taken from the image file, no other attributes are valid with SEC_IMAGE.
SEC_NOCACHE	All pages of a section are to be set as non-cacheable. This attribute is intended for architectures requiring various locking structures to be in memory that is never fetched into the processor's. On 80x86 and MIPS machines, using the cache for these structures only slows down the performance as the hardware keeps the caches coherent. Some device drivers require noncached data so that programs can write through to the physical memory. SEC_NOCACHE requires either the SEC_RESERVE or SEC_COMMIT to also be set.
SEC_RESERVE	Reserves all pages of a section without allocating physical storage. The reserved range of pages cannot be used by any other allocation operations until it is released. Reserved pages can be committed in subsequent calls to the VirtualAlloc function. This attribute is valid only if the hFile parameter is (HANDLE)0xFFFFFFFF; that is, a file mapping object backed by the operating sytem paging file.
dwMaximumSizeHigh

Specifies the high-order 32 bits of the maximum size of the file-mapping object.

dwMaximumSizeLow

Specifies the low-order 32 bits of the maximum size of the file-mapping object. If this parameter and dwMaximumSizeHig are zero, the maximum size of the file-mapping object is equal to the current size of the file identified by hFile.

lpName

Points to a null-terminated string specifying the name of the mapping object. The name can contain any character except the backslash character (\).

If this parameter matches the name of an existing named mapping object, the function requests access to the mapping object with the protection specified by flProtect.

If this parameter is NULL, the mapping object is created without a name.

Return Value

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, call GetLastError.

Remarks

After a file-mapping object has been created, the size of the file must not exceed the size of the file-mapping object; if it does, not all of the file's contents will be available for sharing.

If an application specifies a size for the file-mapping object that is larger than the size of the actual named file on disk, the file on disk is grown to match the specified size of the file-mapping object.

The handle that CreateFileMapping returns has full access to the new file-mapping object. It can be used with any function that requires a handle to a file-mapping object. File-mapping objects can be shared either through process creation, through handle duplication, or by name. For information on duplicating handles, see DuplicateHandle. For information on opening a file-mapping object by name, see OpenFileMapping.

Creating a file-mapping object creates the potential for mapping a view of the file but does not map the view. The MapViewOfFile and MapViewOfFileEx functions map a view of a file into a process's address space.

With one important exception, file views derived from a single file-mapping object are coherent, or identical, at a given time. If multiple processes have handles of the same file-mapping object, they see a coherent view of the data when they map a view of the file.

The exception has to do with remote files. Although CreateFileMapping works with remote files, it does not keep them coherent. For example, if two computers both map a file as writable, and both change the same page, each computer will only see its own writes to the page. When the data gets updated on the disk, it is not merged.

A mapped file and a file accessed by means of the input and output (I/O) functions (ReadFile and WriteFile) are not necessarily coherent.

To fully close a file mapping object, an application must unmap all mapped views of the file mapping object by calling UnmapViewOfFile, and close the file mapping object handle by calling CloseHandle. The order in which these functions are called does not matter. The call to UnmapViewOfFile is necessary because mapped views of a file mapping object maintain internal open handles to the object, and a file mapping object will not close until all open handles to it are closed.

Example

To implement a mapping-object creation function that fails if the object already exists, an application can use the following code.

hMap = CreateFileMapping(...);

if (hMap != NULL && GetLastError() == ERROR_ALREADY_EXISTS) {

    CloseHandle(hMap);

    hMap = NULL;

}

return hMap;

See Also

CloseHandle, DuplicateHandle, MapViewOfFile, MapViewOfFileEx, OpenFileMapping, ReadFile, SECURITY_ATTRIBUTES, UnmapViewOfFile, VirtualAlloc, WriteFile


 CreateFont

The CreateFont function creates a logical font that has specific characteristics. The logical font can subsequently be selected as the font for any device.

HFONT CreateFont(

int  nHeight,	// logical height of font
int  nWidth,	// logical average character width
int  nEscapement,	// angle of escapement
int  nOrientation,	// base-line orientation angle
int  fnWeight,	// font weight
DWORD  fdwItalic,	// italic attribute flag
DWORD  fdwUnderline,	// underline attribute flag
DWORD  fdwStrikeOut,	// strikeout attribute flag
DWORD  fdwCharSet,	// character set identifier
DWORD  fdwOutputPrecision,	// output precision
DWORD  fdwClipPrecision,	// clipping precision
DWORD  fdwQuality,	// output quality
DWORD  fdwPitchAndFamily,	// pitch and family
LPCTSTR  lpszFace	// address of typeface name string
);
Parameters

nHeight

Specifies the desired height, in logical units, of the requested font's character cell or character. The character height value (also known as the em height) is the character cell height value minus the internal-leading value. The font mapper interprets the value specified in nHeight in the following manner:

Value	Meaning
> 0	The font mapper matches this value against available character cell height values.
0	The font mapper uses a default height value when it searches for a match.
< 0	The font mapper matches the absolute value of nHeight 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:

Windows NT

ANSI_CHARSET
UNICODE_CHARSET
SYMBOL_CHARSET
SHIFTJIS_CHARSET
HANGEUL_CHARSET
CHINESEBIG5_CHARSET
OEM_CHARSET

Windows 95

ANSI_CHARSET
DEFAULT_CHARSET
SYMBOL_CHARSET
SHIFTJIS_CHARSET
HANGEUL_CHARSET
GB2312_CHARSET
CHINESEBIG5_CHARSET
GREEK_CHARSET
TURKISH_CHARSET
HEBREW_CHARSET
ARABIC_CHARSET
BALTIC_CHARSET
RUSSIAN_CHARSET
THAI_CHARSET
EASTEUROPE_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.

This parameter is important in the font mapping process. To ensure consistent results, specify a specific character set. If you specify a typeface name in the lpszFace parameter, make sure that the fdwCharSet value matches the character set of the typeface specified in lpszFace.

fdwOutputPrecision

Specifies the 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

Windows NT: Applications can use the OUT_DEVICE_PRECIS, OUT_RASTER_PRECIS, and OUT_TT_ONLY_PRECIS values to control how the font mapper chooses a font when the operating system contains more than one font with a given name. For example, if an operating system contains a font named Symbol in raster and TrueType form, specifying OUT_TT_ONLY_PRECIS forces the font mapper to choose the TrueType version. (Specifying OUT_TT_ONLY_PRECIS forces the font mapper to choose a TrueType font for a specified device or raster font, even if there is no TrueType font of the same name.)

Windows 95: Applications can use the OUT_DEVICE_PRECIS, OUT_RASTER_PRECIS, and OUT_TT_PRECIS values to control how the font mapper chooses a font when the operating system contains more than one font with a given name. For example, if an operating system contains a font named Symbol in raster and TrueType form, specifying OUT_TT_PRECIS forces the font mapper to choose the TrueType version. (Specifying OUT_TT_PRECIS forces the font mapper to choose a TrueType font whenever the specified font name matches both a TrueType font and either a device or raster font.)

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

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

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 EnumFontFamilies function can be used to enumerate the typeface names of all currently available fonts.

Return Value

If the function succeeds, the return value is a handle of a logical font.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

DeleteObject, SelectObject, EnumFontFamilies


 CreateFontIndirect

The CreateFontIndirect function creates a logical font that has the characteristics specified in the specified structure. The font can subsequently be selected as the current font for any device context.

HFONT CreateFontIndirect(

CONST LOGFONT  *lplf	// address of logical font structure
);
Parameters

lplf

Points to a LOGFONT structure that defines the characteristics of the logical font.

Return Value

If the function succeeds, the return value is a handle of a logical font.

If the function fails, the return value is NULL.

Remarks

The CreateFontIndirect function creates a logical font with the characteristics specified in the LOGFONT structure. When this font is selected by using the SelectObject function, GDI's font mapper attempts to match the logical font with an existing physical font. If it fails to find an exact match, it provides an alternative whose characteristics match as many of the requested characteristics as possible.

See Also

DeleteObject, LOGFONT, SelectObject


 CreateHalftonePalette

The CreateHalftonePalette function creates a halftone palette for the specified device context.

HPALETTE CreateHalftonePalette(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value identifies a logical halftone palette.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application should create a halftone palette when the stretching mode of a device context is set to HALFTONE. The logical halftone palette returned by CreateHalftonePalette should then be selected and realized into the device context before the StretchBlt or StretchDIBits function is called.

See Also

RealizePalette, SelectPalette, SetStretchBltMode, StretchDIBits, StretchBlt


 CreateHatchBrush

The CreateHatchBrush function creates a logical brush that has the specified hatch pattern and color.

HBRUSH CreateHatchBrush(

int  fnStyle,	// hatch style
COLORREF  clrref	// color value
);
Parameters

fnStyle

Specifies the hatch style of the brush. This parameter can be any one of the following values:

Value	Meaning
HS_BDIAGONAL	45-degree downward left-to-right hatch
HS_CROSS	Horizontal and vertical crosshatch
HS_DIAGCROSS	45-degree crosshatch
HS_FDIAGONAL	45-degree upward left-to-right hatch
HS_HORIZONTAL	Horizontal hatch
HS_VERTICAL	Vertical hatch
clrref

Specifies the foreground color of the brush that is used for the hatches.

Return Value

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

A brush is a bitmap that Windows uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreateHatchBrush, it can select that brush into any device context by calling the SelectObject function.

If an application uses a hatch brush to fill the backgrounds of both a parent and a child window with matching color, it may be necessary to set the brush origin before painting the background of the child window. You can do this by having your application call the SetBrushOrgEx function. Your application can retrieve the current brush origin by calling the GetBrushOrgEx function.

See Also

CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreatePatternBrush, CreateSolidBrush, DeleteObject, GetBrushOrgEx, SelectObject, SetBrushOrgEx


 CreateIC

The CreateIC function creates an information context for the specified device. The information context provides a fast way to get information about the device without creating a device context.

HDC CreateIC(

LPCTSTR  lpszDriver,	// 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
);
Parameters

lpszDriver

Points to a null-terminated character string that specifies the name of the device driver (for example, "Epson").

lpszDevice

Points to a null-terminated character string that specifies the name of the specific output device being used, as shown by the Print Manager (for example, "Epson FX-80"). It is not the printer model name. The lpszDevice parameter must be used.

lpszOutput

Points to a null-terminated character string that specifies the file or device name for the physical output medium (file or output port). This parameter is ignored; it is present only to keep the function prototype identical with Windows version 3.1.

lpdvmInit

Points to a DEVMODE structure containing device-specific initialization data for the device driver. The DocumentProperties function retrieves this structure filled in for a given device. The lpdvmInit parameter must be NULL if the device driver is to use the default initialization (if any) specified by the user.

Return Value

If the function succeeds, the return value is the handle of an information context.

If the function fails, the return value is NULL.

Remarks

An error occurs if an application calls a GDI drawing function and supplies a handle identifying an information context.

See Also

DocumentProperties, DEVMODE, GetDeviceCaps


 CreateIcon

The CreateIcon function creates an icon that has the specified size, colors, and bit patterns.

HICON CreateIcon(

HINSTANCE  hInstance,	// 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
);
Parameters

hInstance

Identifies the instance of the module creating the icon.

nWidth

Specifies the width, in pixels, of the icon.

nHeight

Specifies the height, in pixels, of the icon.

cPlanes

Specifies the number of planes in the XOR bitmask of the icon.

cBitsPixel

Specifies the number of bits per pixel in the XOR bitmask of the icon.

lpbANDbits

Points to an array of bytes that contains the bit values for the AND bitmask of the icon. This bitmask describes a monochrome bitmap.

lpbXORbits

Points to an array of bytes that contains the bit values for the XOR bitmask of the icon. This bitmask describes a monochrome or device-dependent color bitmap.

Return Value

If the function succeeds, the return value is the handle of an icon.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The nWidth and nHeight parameters must specify a width and height supported by the current display driver, because the system cannot create icons of other sizes. To determine the width and height supported by the display driver, use the GetSystemMetrics function, specifying the SM_CXICON or SM_CYICON value.

CreateIcon applies the following truth table to the AND and XOR bitmasks:

AND bitmask	XOR bitmask	Display
0	0	Black
0	1	White
1	0	Screen
1	1	Reverse screen
Before closing, an application must call the DestroyIcon function to free system resources associated with the icon.

See Also

DestroyIcon, GetSystemMetrics


 CreateIconFromResource

The CreateIconFromResource function creates an icon or cursor from resource bits describing the icon.

HICON CreateIconFromResource(

PBYTE  presbits,	// address of icon or cursor bits
DWORD  dwResSize,	// number of bytes in bit buffer
BOOL  fIcon,	// icon or cursor flag
DWORD  dwVer	// Windows format version
);
Parameters

presbits

Points to a buffer containing the icon or cursor resource bits. These bits are typically loaded by calls to the LookupIconIdFromDirectory (in Windows 95 you can also call LookupIconIdFromDirectoryEx) and LoadResource functions.

dwResSize

Specifies the size, in bytes, of the set of bits pointed to by the presbits parameter.

fIcon

Specifies whether an icon or a cursor is to be created. If this parameter is TRUE, an icon is to be created. If it is FALSE, a cursor is to be created.

dwVer

Specifies the version number of the icon or cursor format for the resource bits pointed to by the presbits parameter. This parameter can be one of the following values:

Format	dwVer
Windows 2.x	0x00020000
Windows 3.x	0x00030000
All Microsoft Win32-based applications use the Windows 3.x format for icons and cursors.

Return Value

If the function succeeds, the return value is the handle of the icon or cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CreateIconFromResource, CreateIconIndirect, GetIconInfo, and LookupIconIdFromDirectory functions (and in Windows 95 the CreateIconFromResourceEx and LookupIconIdFromDirectoryEx functions) allow shell applications and icon browsers to examine and use resources from throughout the system.

See Also

CreateIconFromResource, CreateIconFromResourceEx, CreateIconIndirect, GetIconInfo, LoadResource, LookupIconIdFromDirectory LookupIconIdFromDirectoryEx


CreateIconFromResourceEx  (preliminaryWindows 95)
 CreateIconFromResourceE  [image] x  (preliminary−Windows 95)

The CreateIconFromResourceEx function creates an icon or cursor from resource bits describing the icon.

HICON CreateIconFromResourceEx(

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
int  cxDesired,	// desired width of icon or cursor
int  cyDesired,	// desired height of icon or cursor
UINT  uFlags	// load resource flags
);
Parameters

pbIconBits

Points to a buffer containing the icon or cursor resource bits. These bits are typically loaded by calls to the LookupIconIdFromDirectoryEx and LoadResource functions.

cbIconBits

Specifies the size, in bytes, of the set of bits pointed to by the pbIconBits parameter.

fIcon

Specifies whether an icon or a cursor is to be created. If this parameter is TRUE, an icon is to be created. If it is FALSE, a cursor is to be created.

dwVersion

Specifies the version number of the icon or cursor format for the resource bits pointed to by the pbIconBits parameter. This parameter can be one of the following values:

Format	dwVersion
Windows 2.x	0x00020000
Windows 3.x	0x00030000
All Win32-based applications use the Windows 3.x format for icons and cursors.

cxDesired

Specifies the desired width, in pixels, of the icon or cursor. If this parameter is zero and uFlags does not include LR_LOADREALSIZE, the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width.

cyDesired

Specifies the desired height, in pixels, of the icon or cursor. If this parameter is zero and uFlags does not include LR_LOADREALSIZE, the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the height.

uFlags

Specifies a combination of the following values:

Value	Meaning
LR_DEFAULTCOLOR	Uses the default color format.
LR_LOADREALSIZE	Sets the width and height as specified by the biWidth and biHeight members of the BITMAPINFOHEADER structure that defines the icon or cursor. The cxDesired and cyDesired parameters are ignored.
LR_MONOCHROME	Creates a monochrome icon or cursor.
Return Value

If the function succeeds, the return value is the handle of the icon or cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The CreateIconFromResourceEx, CreateIconFromResource, CreateIconIndirect, GetIconInfo, and LookupIconIdFromDirectoryEx functions allow shell applications and icon browsers to examine and use resources from throughout the system.

See Also

BITMAPINFOHEADER, CreateIconFromResource, CreateIconIndirect, GetIconInfo, LoadResource, LookupIconIdFromDirectoryEx


 CreateIconIndirect

The CreateIconIndirect function creates an icon or cursor from an ICONINFO structure.

HICON CreateIconIndirect(

PICONINFO  piconinfo	// address of icon information structure
);
Parameters

piconinfo

Points to an ICONINFO structure the function uses to create the icon or cursor.

Return Value

If the function succeeds, the return value is the handle of the icon or cursor that is created.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The system copies the bitmaps in the ICONINFO structure before creating the icon or cursor. The application must continue to manage the original bitmaps and delete them when they are no longer necessary.

See Also

CreateIcon, CreateIconFromResource, DestroyIcon, DrawIcon, GetIconInfo, ICONINFO, LoadIcon, LookupIconIdFromDirectory


 CreateIoCompletionPort

The CreateIoCompletionPort function associates an input/output completion port with an instance of an opened file. The function can use an existing input/output completion port, or it can create a new input/output completion port.

Associating an instance of an opened file with an input/output completion port lets an application receive notification of the completion of asynchronous input/output operations involving that file.

HANDLE CreateIoCompletionPort (

HANDLE FileHandle,	// file handle to associate with I/O completion port
HANDLE ExistingCompletionPort,	// optional handle to existing I/O completion port
DWORD CompletionKey,	// per-file completion key for I/O completion packets
DWORD NumberOfConcurrentThreads	// number of threads allowed to execute concurrently
);
Parameters

FileHandle

Handle to a file opened for overlapped input/output completion. You must specify the FILE_FLAG_OVERLAPPED flag to obtain such a handle.

The CreateIoCompletionPort function associates the file with an existing input/output completion port, or with one that the function creates.

Once an instance of an open file is associated with an I/O completion port, it cannot be used in ReadFileEx or WriteFileEx operations.

It is best not to share such an associated file through either handle inheritance or a call to the DuplicateHandle function. Input/output operations done with such duplicate handles will generate completion notifications.

ExistingCompletionPort

Handle to an existing I/O completion port. This parameter can be NULL.

If this parameter is not NULL, it specifies an existing completion port that the function is to associate with the file specified by FileHandle.

If this parameter is NULL, the function creates a new input/output completion port that it associates with the specified file.

CompletionKey

Specifies a per-file completion key that will be included in every input/output completion packet for the specified file.

NumberOfConcurrentThreads

Specifies the number of threads that are allowed to execute concurrently.

If one of the threads enters a wait state, then another thread is allowed to proceed. There may be brief periods when the number of active threads exceeds the specified value, but the operating system quickly brings the number back down.

A value of 0 for this parameter tells the operating system to allow as many threads as there are processors in the system.

Return Value

If the function succeeds, the return value is the handle of the I/O completion port that is associated with the specified file. This return value is not NULL.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The Win32 I/O system can be instructed to send I/O completion notification packets to input/output completion ports, where they are queued up. The CreateIoCompletionPort function provides a mechanism for this.

When you perform an input/output operation with a file handle that has an associated input/output completion port, the I/O system sends a completion notification packet to the completion port when the I/O operation completes. The I/O completion port places the completion packet in a first-in-first-out queue. Use the GetQueuedCompletionStatus function to retrieve these queued I/O completion packets.

See Also

DuplicateHandle, GetQueuedCompletionStatus, ReadFileEx, WriteFileEx


 CreateMailslot

The CreateMailslot function creates a mailslot with the specified name and returns a handle that a mailslot server can use to perform operations on the mailslot. The mailslot is local to the computer that creates it. An error occurs if a mailslot with the specified name already exists.

HANDLE CreateMailslot(

LPCTSTR  lpName,	// address of string for mailslot name
DWORD  nMaxMessageSize,	// maximum message size
DWORD  lReadTimeout,	// milliseconds before read time-out
LPSECURITY_ATTRIBUTES  lpSecurityAttributes	// address of security structure
);
Parameters

lpName

Points to a null-terminated string specifying the name of the mailslot. This name must have the following form:

\\.\mailslot\[path]name

The name field must be unique. The name may include multiple levels of pseudodirectories separated by backslashes. For example, both \\.\mailslot\example_mailslot_name and \\.\mailslot\abc\def\ghi are valid names.

nMaxMessageSize

Specifies the maximum size, in bytes, of a single message that can be written to the mailslots. To specify that the message can be of any size, set this value to zero.

lReadTimeout

Specifies the amount of time, in milliseconds, a read operation can wait for a message to be written to the mailslot before a time-out occurs. The following values have special meanings:

Value	Meaning
0	Returns immediately if no message is present. (The system does not treat an immediate return as an error.)
MAILSLOT_WAIT_FOREVER	Waits forever for a message.
This time-out value applies to all subsequent read operations and all inherited mailslot handles.

lpSecurityAttributes

Points to a SECURITY_ATTRIBUTES structure specifying the security attributes for the mailslot.

If lpSecurityAttributes is NULL, the mailslot is created with a default security descriptor, and the resulting handle is not inherited.

Return Value

If the function succeeds, the return value is a handle to the mailslot, for use in server mailslot operations.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The mailslot exists until one of the following conditions is true:

•	The last (possibly inherited or duplicated) handle to it is closed using the CloseHandle function.

•	The process owning the last (possibly inherited or duplicated) handle exits.

Both Windows NT and Windows 95 use the second method to destroy mailslots.

To write a message to a mailslot, a process uses the CreateFile function, specifying the mailslot name by using one of the following formats:

Format	Usage
\\.\mailslot\name	Retrieves a client handle to a local mailslot.
\\computername\mailslot\name	Retrieves a client handle to a remote mailslot.
\\domainname\mailslot\name	Retrieves a client handle to all mailslots with the 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. If the application attempts to do so, the WriteFile function fails and GetLastError returns ERROR_BAD_NETPATH.

An application must specify the FILE_SHARE_READ flag when using CreateFile to retrieve a client handle to a mailslot.

See Also

CloseHandle, CreateFile, GetMailslotInfo, SECURITY_ATTRIBUTES, SetMailslotInfo, WriteFile


CreateMappedBitmap  (preliminaryWindows NT)
 CreateMappedBitmap  (preliminary−Windows NT)

The CreateMappedBitmap function creates a bitmap for use in a toolbar.

HBITMAP CreateMappedBitmap(

HINSTANCE  hInstance,
int  idBitmap,
UINT  wFlags,
LPCOLORMAP lpColorMap,
int  iNumMaps
);
Parameters

hInstance

Handle to the module instance with the executable file that contains the bitmap resource.

idBitmap

Resource identifier of the bitmap resource.

wFlags

Bitmap flag. This parameter can be zero or the following value:

Value	Meaning
CMB_MASKED	Uses a bitmap as a mask.
lpColorMap

Pointer to a COLORMAP structure that contains the color information needed to map the bitmaps. If this parameter is NULL, the function uses the default color map.

iNumMaps

Number of color maps pointed to by lpColorMap.

Return Value

If the function succeeds, the return value is the handle to the bitmap.

If the function fails, the return value is NULL.

Remarks

The function creates a new bitmap using the bitmap data and colors specified by the given bitmap resource and the color mapping information.

See Also

COLORMAP


 CreateMDIWindow

The CreateMDIWindow function creates a multiple document interface (MDI) child window.

HWND CreateMDIWindow(

LPTSTR  lpClassName,	// address of registered child class name
LPTSTR  lpWindowName,	// 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  hInstance,	// handle of application instance
LPARAM  lParam	// application-defined value
);
Parameters

lpClassName

Points to a null-terminated string specifying the window class of the MDI child window. The class name must have been registered by a call to the RegisterClass function.

lpWindowName

Points to a null-terminated string that represents the window name. Windows displays the name in the title bar of the child window.

dwStyle

Specifies the style of the MDI child window. If the MDI client window is created with the MDIS_ALLCHILDSTYLES window style, this parameter can be any combination of the window styles listed in the description of the CreateWindow function. Otherwise, this parameter can be one or more of the following values:

Value	Meaning
WS_MINIMIZE	Creates an MDI child window that is initially minimized.
WS_MAXIMIZE	Creates an MDI child window that is initially maximized.
WS_HSCROLL	Creates an MDI child window that has a horizontal scroll bar.
WS_VSCROLL	Creates an MDI child window that has a vertical scroll bar.
X

Specifies the initial horizontal position, in client coordinates, of the MDI child window. If this parameter is CW_USEDEFAULT, the MDI child window is assigned the default horizontal position.

Y

Specifies the initial vertical position, in client coordinates, of the MDI child window. If this parameter is CW_USEDEFAULT, the MDI child window is assigned the default vertical position.

nWidth

Specifies the initial width, in device units, of the MDI child window. If this parameter is CW_USEDEFAULT, the MDI child window is assigned the default width.

nHeight

Specifies the initial height, in device units, of the MDI child window. If this parameter is set to CW_USEDEFAULT, the MDI child window is assigned the default height.

hWndParent

Identifies the MDI client window that will be the parent of the new MDI child window.

hInstance

Identifies the instance of the application creating the MDI child window.

lParam

Specifies an application-defined value.

Return Value

If the function succeeds, the return value is the handle of the created window.

If the function fails, the return value is NULL.

Remarks

Using the CreateMDIWindow function is similar to sending the WM_MDICREATE message to an MDI client window, except that the function can create an MDI child window in a different thread, while the message cannot.

See Also

CreateWindow, RegisterClass, WM_MDICREATE


 CreateMenu

The CreateMenu function creates a menu. The menu is initially empty, but it can be filled with menu items by using the AppendMenu and InsertMenu functions.

HMENU CreateMenu(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the handle of the newly created menu.

If the function fails, the return value is NULL.

Remarks

Resources associated with a menu that is assigned to a window are freed automatically. If the menu is not assigned to a window, an application must free system resources associated with the menu before closing. An application frees menu resources by calling the DestroyMenu function.

See Also

AppendMenu, DestroyMenu, InsertMenu, SetMenu


 CreateMetaFile

The CreateMetaFile function creates a device context for a Windows-format metafile.

This function is provided for compatibility with earlier 16-bit versions of Microsoft Windows. Win32-based applications should use the CreateEnhMetaFile function.

HDC CreateMetaFile(

LPCTSTR  lpszFile	// address of filename string
);
Parameters

lpszFile

Points to the filename for the Windows-format metafile to be created. If this parameter is NULL, the Windows-format metafile is memory based and its contents are lost when it is deleted by using the DeleteMetaFile function.

Return Value

If the function succeeds, the return value is a handle of the device context for the Windows-format metafile.

If the function fails, the return value is NULL.

Remarks

Where text arguments must use Unicode characters, use 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 device context is used with a GDI output function, the return value of that function becomes TRUE if the function is recorded and FALSE otherwise. When an object is selected by using the SelectObject function, only a copy of the object is recorded. The object still belongs to the application.

To create a scalable Windows-format metafile, record the graphics output in the MM_ANISOTROPIC mapping mode. The file cannot contain functions that modify the viewport origin and extents, nor can it contain device-dependent functions such as the SelectClipRgn function. Once created, the Windows metafile can be scaled and rendered to any output device-format by defining the viewport origin and extents of the picture before playing it.

See Also

CloseMetaFile, CreateEnhMetaFile, DeleteMetaFile, GetTextColor, PolyBezier, SelectClipRgn, SelectObject


 CreateMutex

The CreateMutex function creates a named or unnamed mutex object.

HANDLE CreateMutex(

LPSECURITY_ATTRIBUTES  lpMutexAttributes,	// address of security attributes
BOOL  bInitialOwner,	// flag for initial ownership
LPCTSTR  lpName	// address of mutex-object name
);
Parameters

lpMutexAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the mutex object.

If lpMutexAttributes is NULL, the mutex object is created with a default security descriptor and the resulting handle is not inheritable.

bInitialOwner

Specifies the initial owner of the mutex object. If TRUE, the calling thread requests immediate ownership of the mutex object. Otherwise, the mutex is not owned.

lpName

Points to a null-terminated string specifying the name of the mutex object. The name is limited to MAX_PATH characters and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive.

If lpName matches the name of an existing named mutex object, this function requests MUTEX_ALL_ACCESS access to the existing object. In this case, the bInitialOwner parameter is ignored because it has already been set by the creating process. If the lpMutexAttributes parameter is not NULL, it determines whether the handle can be inherited, but its security-descriptor member is ignored.

If lpName is NULL, the mutex object is created without a name.

If lpName matches the name of an existing event, semaphore, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because event, mutex, semaphore, and file-mapping objects share the same name space.

Return Value

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, call GetLastError.

Remarks

The handle returned by CreateMutex has MUTEX_ALL_ACCESS access to the new mutex object and can be used in any function that requires a handle 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 bInitialOwner flag to request immediate ownership of the mutex. Otherwise, a thread must use one of the wait functions to request ownership. When the mutex's state is signaled, one waiting thread is granted ownership, the mutex's state changes to nonsignaled, and the wait function returns. Only one thread can own a mutex at any given time. The owning thread uses the ReleaseMutex function to release its ownership.

The thread that owns a mutex can specify the same mutex in repeated wait function calls without blocking its execution. Typically, you would not wait repeatedly for the same mutex, but this mechanism prevents a thread from deadlocking itself while waiting for a mutex that it already owns. However, to release its ownership, the thread must call ReleaseMutex once for each time that the mutex satisfied a wait.

Two or more processes can call CreateMutex to create the same named mutex. The first process actually creates the mutex, and subsequent processes open a handle 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 bInitialOwner flag to FALSE; otherwise, it can be difficult to be certain which process has initial ownership.

Multiple processes can have handles of the same mutex object, enabling use of the object for interprocess synchronization. The following object-sharing mechanisms are available:

•	A child process created by the CreateProcess function can inherit a handle of a mutex object if the lpMutexAttributes parameter of CreateMutex enabled inheritance.

•	A process can specify the mutex-object handle in a call to the DuplicateHandle function to create a duplicate handle that can be used by another process.

•	A process can specify the name of a mutex object in a call to the OpenMutex or CreateMutex function.

Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The mutex object is destroyed when its last handle has been closed.

See Also

CloseHandle, CreateProcess, DuplicateHandle, MsgWaitForMultipleObjects, OpenMutex, ReleaseMutex, SECURITY_ATTRIBUTES, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


 CreateNamedPipe

The CreateNamedPipe function creates an instance of a named pipe and returns a handle for subsequent pipe operations. A named pipe server process uses this function either to create the first instance of a specific named pipe and establish its basic attributes or to create a new instance of an existing named pipe.

HANDLE CreateNamedPipe(

LPCTSTR  lpName,	// address of pipe name
DWORD  dwOpenMode,	// pipe open mode
DWORD  dwPipeMode,	// pipe-specific modes
DWORD  nMaxInstances,	// maximum number of instances
DWORD  nOutBufferSize,	// output buffer size, in bytes
DWORD  nInBufferSize,	// input buffer size, in bytes
DWORD  nDefaultTimeOut,	// time-out time, in milliseconds
LPSECURITY_ATTRIBUTES  lpSecurityAttributes	// address of security attributes structure
);
Parameters

lpName

Points to the null-terminated string that uniquely identifies the pipe. The string must have the following form:

\\.\pipe\pipename

The pipename part of the name can include any character other than a backslash, including numbers and special characters. The entire pipe name string can be up to 256 characters long. Pipe names are not case sensitive.

dwOpenMode

Specifies the pipe access mode, the overlapped mode, the write-through mode, and the security access mode of the pipe handle.

This parameter must specify one of the following pipe access mode flags. The same mode must be specified for each instance of the pipe:

Mode	Description
PIPE_ACCESS_DUPLEX	The pipe is bidirectional; both server and client processes can read from and write to the pipe. This mode gives the server the equivalent of GENERIC_READ | GENERIC_WRITE access to the pipe. The client can specify GENERIC_READ or GENERIC_WRITE, or both, when it connects to the pipe using the CreateFile function.
PIPE_ACCESS_INBOUND	The flow of data in the pipe goes from client to server only. This mode gives the server the equivalent of GENERIC_READ access to the pipe. The client must specify GENERIC_WRITE access when connecting to the pipe.
PIPE_ACCESS_OUTBOUND	The flow of data in the pipe goes from server to client only. This mode gives the server the equivalent of GENERIC_WRITE access to the pipe. The client must specify GENERIC_READ access when connecting to the pipe.
This parameter can also include either or both of the following flags, which enable write-through mode and overlapped mode. These modes can be different for different instances of the same pipe.

Mode	Description
FILE_FLAG_WRITE_THROUGH
	Write-through mode is enabled. This mode affects only write operations on byte-type pipes and, then, only when the client and server processes are on different computers. If this mode is enabled, functions writing to a named pipe do not return until the data written is transmitted across the network and is in the pipe's buffer on the remote computer. If this mode is not enabled, the system enhances the efficiency of network operations by buffering data until a minimum number of bytes accumulate or until a maximum time elapses.
FILE_FLAG_OVERLAPPED
	Overlapped mode is enabled. If this mode is enabled, functions performing read, write, and connect operations that may take a significant time to be completed can return immediately. This mode enables the thread that started the operation to perform other operations while the time-consuming operation executes in the background. For example, in overlapped mode, a thread can handle simultaneous input and output (I/O) operations on multiple instances of a pipe or perform simultaneous read and write operations on the same pipe handle. If overlapped mode is not enabled, functions performing read, write, and connect operations on the pipe handle do not return until the operation is finished. The ReadFileEx and WriteFileEx functions can only be used with a pipe handle in overlapped mode. The ReadFile, WriteFile, ConnectNamedPipe, and TransactNamedPipe functions can execute either synchronously or as overlapped operations.
This parameter can include any combination of the following security access mode flags. These modes can be different for different instances of the same pipe. They can be specified without concern for what other dwOpenMode modes have been specified.

Mode	Description
WRITE_DAC	The caller will have write access to the named pipe's discretionary access control list (ACL).
WRITE_OWNER	The caller will have write access to the named pipe's owner.
ACCESS_SYSTEM_SECURITY	The caller will have write access to the named pipe's system ACL.
dwPipeMode

Specifies the type, read, and wait modes of the pipe handle.

One of the following type mode flags can be specified. The same type mode must be specified for each instance of the pipe. If you specify zero, the parameter defaults to byte-type mode.

Mode	Description
PIPE_TYPE_BYTE	Data is written to the pipe as a stream of bytes. This mode cannot be used with PIPE_READMODE_MESSAGE.
PIPE_TYPE_MESSAGE	Data is written to the pipe as a stream of messages. This mode can be used with either PIPE_READMODE_MESSAGE or PIPE_READMODE_BYTE.
One of the following read mode flags can be specified. Different instances of the same pipe can specify different read modes. If you specify zero, the parameter defaults to byte-read mode.

Mode	Description
PIPE_READMODE_BYTE	Data is read from the pipe as a stream of bytes. This mode can be used with either PIPE_TYPE_MESSAGE or PIPE_TYPE_BYTE.
PIPE_READMODE_MESSAGE	Data is read from the pipe as a stream of messages. This mode can be only used if PIPE_TYPE_MESSAGE is also specified.
One of the following wait mode flags can be specified. Different instances of the same pipe can specify different wait modes. If you specify zero, the parameter defaults to blocking mode.

Mode	Description
PIPE_WAIT	Blocking mode is enabled. When the pipe handle is specified in the ReadFile, WriteFile, or ConnectNamedPipe function, the operations are not completed until there is data to read, all data is written, or a client is connected. Use of this mode can mean waiting indefinitely in some situations for a client process to perform an action.
PIPE_NOWAIT	Nonblocking mode is enabled. In this mode, ReadFile, WriteFile, and ConnectNamedPipe always return immediately. Note that nonblocking mode is supported for compatibility with Microsoft LAN Manager version 2.0 and should not be used to achieve asynchronous I/O with named pipes.
nMaxInstances

Specifies the maximum number of instances that can be created for this pipe. The same number must be specified for all instances. Acceptable values are in the range 1 through PIPE_UNLIMITED_INSTANCES. If this parameter is PIPE_UNLIMITED_INSTANCES, the number of pipe instances that can be created is limited only by the availability of system resources.

nOutBufferSize

Specifies the number of bytes to reserve for the output buffer. For a discussion on sizing named pipe buffers, see the following Remarks section.

nInBufferSize

Specifies the number of bytes to reserve for the input buffer. For a discussion on sizing named pipe buffers, see the following Remarks section.

nDefaultTimeOut

Specifies the default time-out value, in milliseconds, if the WaitNamedPipe function specifies NMPWAIT_USE_DEFAULT_WAIT. Each instance of a named pipe must specify the same value.

lpSecurityAttributes

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 this parameter, this parameter will always have an effect when specified.

If this parameter 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.

Return Value

If the function succeeds, the return value is a handle to the server end of a named pipe instance.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError. The return value is ERROR_INVALID_PARAMETER if nMaxInstances is greater than PIPE_UNLIMITED_INSTANCES.

Remarks

To create an instance of a named pipe by using CreateNamedPipe, the user must have FILE_CREATE_PIPE_INSTANCE access to the named pipe object. If a new named pipe is being created, the access control list (ACL) from the security attributes parameter defines the discretionary access control for the named pipe.

All instances of a named pipe must specify the same pipe type (byte-type or message-type), pipe access (duplex, inbound, or outbound), instance count, and time-out value. If different values are used, this function fails and GetLastError returns ERROR_ACCESS_DENIED.

The input and output buffer sizes are advisory. The actual buffer size reserved for each end of the named pipe is either the system default, the system minimum or maximum, or the specified size rounded up to the next allocation boundary.

An instance of a named pipe is always deleted when the last handle to the instance of the named pipe is closed.

See Also

ConnectNamedPipe, CreateFile, ReadFile, ReadFileEx, SECURITY_ATTRIBUTES, TransactNamedPipe, WaitNamedPipe, WriteFile, WriteFileEx


 CreatePalette

The CreatePalette function creates a logical color palette.

HPALETTE CreatePalette(

CONST LOGPALETTE  *lplgpl	// address of logical color palette
);
Parameters

lplgpl

Points to a LOGPALETTE structure that contains information about the colors in the logical palette.

Return Value

If the function succeeds, the return value is a handle that identifies a logical palette.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

Once an application creates a logical palette, it can select that palette into a device context by calling the SelectPalette function. A palette selected into a device context can be realized by calling the RealizePalette function.

See Also

GetDeviceCaps, LOGPALETTE, RealizePalette, SelectPalette


 CreatePatternBrush

The CreatePatternBrush function creates a logical brush with the specified bitmap pattern. The bitmap cannot be a DIB section bitmap, which is created by the CreateDIBSection function.

HBRUSH CreatePatternBrush(

HBITMAP  hbmp	// handle of bitmap
);
Parameters

hbmp

Identifies the bitmap to be used to create the logical brush.

Return Value

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

A pattern brush is a bitmap that Windows uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreatePatternBrush, it can select that brush into any device context by calling the SelectObject function.

You can delete a pattern brush without affecting the associated bitmap by using the DeleteObject function. Therefore, you can then use this bitmap to create any number of pattern brushes.

A brush created by using a monochrome (1 bit per pixel) bitmap has the text and background colors of the device context to which it is drawn. Pixels represented by a 0 bit are drawn with the current text color; pixels represented by a 1 bit are drawn with the current background color.

The bitmap identified by hbmp cannot be a DIB section, which is a bitmap created by the CreateDIBSection function. If the bitmap is a DIB section, the CreatePatternBrush function fails.

See Also

CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateDIBSection, CreateHatchBrush, DeleteObject, GetBrushOrgEx, LoadBitmap, SelectObject, SetBrushOrgEx


 CreatePen

The CreatePen function creates a logical pen that has the specified style, width, and color. The pen can subsequently be selected into a device context and used to draw lines and curves.

HPEN CreatePen(

int  fnPenStyle,	// pen style
int  nWidth,	// pen width
COLORREF  crColor	// pen color
);
Parameters

fnPenStyle

Specifies the pen style. It can be any one of the following values:

Style	Description
PS_SOLID	Pen is solid.
PS_DASH	Pen is dashed. This style is valid only when the pen width is one or less in device units.
PS_DOT	Pen is dotted. This style is valid only when the pen width is one or less in device units.
PS_DASHDOT	Pen has alternating dashes and dots. This style is valid only when the pen width is one or less in device units.
PS_DASHDOTDOT	Pen has alternating dashes and double dots. This style is valid only when the pen width is one or less in device units.
PS_NULL	Pen is invisible.
PS_INSIDEFRAME	Pen is solid. When this pen is used in any graphics device interface (GDI) drawing function that takes a bounding rectangle, the dimensions of the figure are shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. This applies only to geometric pens.
nWidth

Specifies the width of the pen, in logical units. If nWidth is zero, the pen is a single pixel wide, regardless of the current transformation.

crColor

Specifies a color reference for the pen color.

Return Value

If the function succeeds, the return value is a handle that identifies a logical pen.

If the function fails, the return value is NULL.

Remarks

After an application creates a logical pen, it can select that pen into a device context by calling the SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves.

If the value specified by the nWidth parameter is zero, a line drawn with the created pen will always be a single pixel wide regardless of the current transformation.

If the value specified by nWidth is greater than 1, the fnPenStyle parameter must be PS_NULL, PS_SOLID, or PS_INSIDEFRAME.

If the value specified by nWidth is greater than 1 and fnPenStyle is PS_INSIDEFRAME, the line associated with the pen is drawn inside the frame of all primitives except polygons and polylines.

If the value specified by nWidth is greater than 1, fnPenStyle is PS_INSIDEFRAME, and the color specified by the crColor parameter does not match one of the entries in the logical palette, Windows draws lines by using a dithered color. Dithered colors are not available with solid pens.

When 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

The CreatePenIndirect function creates a logical cosmetic pen that has the style, width, and color specified in a structure.

HPEN CreatePenIndirect(

CONST LOGPEN *  lplgpn	// address of LOGPEN structure
);
Parameters

lplgpn

Points to the LOGPEN structure that specifies the pen's style, width, and color.

Return Value

If the function succeeds, the return value is a handle that identifies a logical cosmetic pen.

If the function fails, the return value is NULL.

Remarks

After an application creates a logical pen, it can select that pen into a device context by calling the SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves.

When 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, LOGPEN, RGB, SelectObject


 CreatePipe

The CreatePipe function creates an anonymous pipe, and returns handles to the read and write ends of the pipe.

BOOL CreatePipe(

PHANDLE  hReadPipe,	// address of variable for read handle
PHANDLE  hWritePipe,	// address of variable for write handle
LPSECURITY_ATTRIBUTES  lpPipeAttributes,	// address of security attributes
DWORD  nSize	// number of bytes reserved for pipe
);
Parameters

hReadPipe

Points to the variable that receives the read handle for the pipe.

hWritePipe

Points to the variable that receives the write handle for the pipe.

lpPipeAttributes

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 lpPipeAttributes is NULL, the pipe is created with a default security descriptor, and the resulting handle is not inherited.

nSize

Specifies the buffer size for the pipe. The size is only a suggestion; the system uses the value to calculate an appropriate buffering mechanism. If this parameter is zero, the system uses the default buffer size.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

CreatePipe creates the pipe, assigning the specified pipe size to the storage buffer. CreatePipe also creates handles that the process uses to read from and write to the buffer in subsequent calls to the ReadFile and WriteFile functions.

When a process uses WriteFile to write to an anonymous pipe, the write operation is not completed until all bytes are written. If the pipe buffer is full before all bytes are written, WriteFile does not return until another process or thread uses ReadFile to make more buffer space available.

See Also

ReadFile, SECURITY_ATTRIBUTES, WriteFile


 CreatePolygonRgn

The CreatePolygonRgn function creates a polygonal region.

HRGN CreatePolygonRgn(

CONST POINT  *lppt,	// address of array of points
int  cPoints,	// number of points in array
int  fnPolyFillMode	// polygon-filling mode
);
Parameters

lppt

Points to an array of POINT structures that define the vertices of the polygon. The polygon is presumed closed. Each vertex can be specified only once.

cPoints

Specifies the number of points in the array.

fnPolyFillMode

Specifies the fill mode used to determine which pixels are in the region. This parameter can be one of the following values:

Value	Meaning
ALTERNATE	Selects alternate mode (fills area between odd-numbered and even-numbered polygon sides on each scan line).
WINDING	Selects winding mode (fills any region with a nonzero winding value).
For more information about these modes, see the SetPolyFillMode function.

Return Value

If the function succeeds, the return value is the handle of the region.

If the function fails, the return value is NULL.

See Also

CreatePolyPolygonRgn, DeleteObject, POINT, SelectObject, SetPolyFillMode


 CreatePolyPolygonRgn

The CreatePolyPolygonRgn function creates a region consisting of a series of polygons. The polygons can overlap.

HRGN CreatePolyPolygonRgn(

CONST POINT  *lppt,	// 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
);
Parameters

lppt

Points to an array of POINT structures that define the vertices of the polygons. The polygons are specified consecutively. Each polygon is presumed closed and each vertex is specified only once.

lpPolyCounts

Points to an array of integers, each of which specifies the number of points in one of the polygons in the array pointed to by lppt.

nCount

Specifies the total number of integers in the array pointed to by lpPolyCounts.

fnPolyFillMode

Specifies the fill mode used to determine which pixels are in the region. This parameter can be one of the following values:

Value	Meaning
ALTERNATE	Selects alternate mode (fills area between odd-numbered and even-numbered polygon sides on each scan line).
WINDING	Selects winding mode (fills any region with a nonzero winding value).
For more information about these modes, see the SetPolyFillMode function.

Return Value

If the function succeeds, the return value is the handle of the region.

If the function fails, the return value is zero.

See Also

CreatePolygonRgn, DeleteObject, POINT, SelectObject, SetPolyFillMode


 CreatePopupMenu

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 (in Windows 95 you can also use the InsertMenuItem function to both append and insert menu items).

HMENU CreatePopupMenu(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the handle of the newly created pop-up menu.

If the function fails, the return value is NULL.

Remarks

The application can add the pop-up menu to an existing menu or pop-up menu, or it can display a floating 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, DestroyMenu, InsertMenu, SetMenu, TrackPopupMenu


 CreatePrivateObjectSecurity

The CreatePrivateObjectSecurity function allocates and initializes a self-relative security descriptor for a new protected server's object. This function is called when a new protected server object is being created.

BOOL CreatePrivateObjectSecurity(

PSECURITY_DESCRIPTOR  ParentDescriptor,	// address of parent directory SD
PSECURITY_DESCRIPTOR  CreatorDescriptor,	// address of creator SD
PSECURITY_DESCRIPTOR *  NewDescriptor,	// address of pointer to new SD
BOOL  IsDirectoryObject,	// container flag for new SD
HANDLE  Token,	// handle of client's access token
PGENERIC_MAPPING  GenericMapping	// address of access-rights structure
);
Parameters

ParentDescriptor

Points to the security descriptor for the parent directory in which a new object is being created. If there is no parent directory, this parameter can be NULL.

CreatorDescriptor

Points to a security descriptor provided by the creator of the object. If the object's creator does not explicitly pass security information for the new object, this parameter is intended to be NULL.

lppsdNew

Points to a pointer to the newly allocated security descriptor created when the function returns.

IsDirectoryObject

Specifies whether the new object is a container. A value of TRUE indicates the object contains other objects, such as a directory.

Token

Identifies the access token for the client process on whose behalf the object is being created. If this is an impersonation token, it must be at SecurityIdentification level or higher. For a full description of the SecurityIdentification impersonation level, see the SECURITY_IMPERSONATION_LEVEL enumerated type

A client token is used to retrieve default security information for the new object, such as its default owner, primary group, and discretionary access-control list. The token must be open for TOKEN_QUERY access.

GenericMapping

Points to a GENERIC_MAPPING structure that specifies the mapping from each generic right to specific rights for the object.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If a system access-control list, or SACL, is specified in the SECURITY_DESCRIPTOR specified by CreatorDescriptor, Token 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, GENERIC_MAPPING, GetPrivateObjectSecurity, GetTokenInformation, OpenProcessToken, SECURITY_DESCRIPTOR, SECURITY_IMPERSONATION_LEVEL, SetPrivateObjectSecurity


 CreateProcess

The CreateProcess function creates a new process and its primary thread. The new process executes the specified executable file.

BOOL CreateProcess(

LPCTSTR  lpApplicationName,	// pointer to name of executable module
LPTSTR  lpCommandLine,	// pointer to command line string
LPSECURITY_ATTRIBUTES  lpProcessAttributes,	// pointer to process security attributes
LPSECURITY_ATTRIBUTES  lpThreadAttributes,	// pointer to thread security attributes
BOOL  bInheritHandles,	// handle inheritance flag
DWORD  dwCreationFlags,	// creation flags
LPVOID  lpEnvironment,	// pointer to new environment block
LPCTSTR  lpCurrentDirectory,	// pointer to current directory name
LPSTARTUPINFO  lpStartupInfo,	// pointer to STARTUPINFO
LPPROCESS_INFORMATION  lpProcessInformation	// pointer to PROCESS_INFORMATION
);
Parameters

lpApplicationName

Pointer to a null-terminated string that specifies the module to execute.

The string can specify the full path and filename of the module to execute.

The string can specify a partial name. In that case, the function uses the current drive and current directory to complete the specification.

The lpApplicationName parameter can be NULL. In that case, the module name must be the first white space-delimited token in the lpCommandLine string.

The specified module can be a Win32-based application. It can be some other type of module (for example, MS-DOS or OS/2) if the appropriate subsystem is available on the local computer.

Windows NT : If the executable module is a 16-bit application, lpApplicationName should be NULL, and the string pointed to by lpCommandLine should specify the executable module. A 16-bit application is one that executes as a VDM or WOW process.

lpCommandLine

Pointer to a null-terminated string that specifies the command line to execute.

The lpCommandLine parameter can be NULL. In that case, the function uses the string pointed to by lpApplicationName as the command line.

If both lpApplicationName and lpCommandLine are non-NULL, *lpApplicationName specifies the module to execute, and *lpCommandLine specifies the command line. The new process can use GetCommandLine to retrieve the entire command line. C runtime processes can use the argc and argv arguments.

If lpApplicationName is NULL, the first white space-delimited token of the command line specifies the module name. If the filename does not contain an extension, .EXE is assumed. If the filename ends in a period (.) with no extension, or the filename contains a path, .EXE is not appended. If the filename does not contain a directory path, Windows searches for the executable file in the following sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT only: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

If the process to be created is an MS-DOS - based or Windows-based application, lpCommandLine should be a full command line in which the first element is the application name. Because this also works well for Win32-based applications, it is the most robust way to set lpCommandLine.

lpProcessAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the created process.

If lpProcessAttributes is NULL, the process is created with a default security descriptor, and the resulting handle is not inherited.

lpThreadAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the primary thread of the new process. If lpThreadAttributes is NULL, the process is created with a default security descriptor, and the resulting handle is not inherited.

bInheritHandles

Indicates whether the new process inherits handles from the calling process. If TRUE, each inheritable open handle in the calling process is inherited by the new process. Inherited handles have the same value and access privileges as the original handles.

dwCreationFlags

Specifies additional flags that control the priority class and the creation of the process. The following creation flags can be specified in any combination, except as noted:

Value	Meaning
CREATE_DEFAULT_ERROR_MODE
	The new process does not inherit the error mode of the calling process. Instead, CreateProcess gives the new process the current default error mode. An application sets the current default error mode by calling SetErrorMode. This flag is particularly useful for multi-threaded shell applications that run with hard errors disabled.  The default behavior for CreateProcess is for the new process to inherit the error mode of the caller. Setting this flag changes that default behavior.
CREATE_NEW_CONSOLE
	The new process has a new console, instead of inheriting the parent's console. This flag cannot be used with the DETACHED_PROCESS flag.
CREATE_NEW_PROCESS_GROUP
	The new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. The process ID of the new process group is the same as the process ID, which is returned in the lpProcessInformation parameter. Process groups are used by the GenerateConsoleCtrlEvent function to enable sending a CTRL+C or CTRL+BREAK signal to a group of console processes.
CREATE_SEPARATE_WOW_VDM
	This flag is only valid only launching a 16-bit Windows program.  If set, the new process is run in a private Virtual DOS Machine (VDM).  By default, all 16-bit Windows programs are run in a single, shared VDM.  The advantage of running separately is that a crash only kills the single VDM; any other programs running in distinct VDMs continue to function normally.  Also, 16-bit Windows applications which are run in separate VDMs have separate input queues. That means that if one application hangs momentarily, applications in separate VDMs continue to receive input.
CREATE_SUSPENDED
	The primary thread of the new process is created in a suspended state, and does not run until the ResumeThread function is called.
CREATE_UNICODE_ENVIRONMENT
	If set, the environment block pointed to by lpEnvironment uses Unicode characters. If clear, the environment block uses ANSI characters.
DEBUG_PROCESS
	If this flag is set, the calling process is treated as a debugger, and the new process is a process being debugged. The system notifies the debugger of all debug events that occur in the process being debugged. If you create a process with this flag set, only the calling thread (the thread that called CreateProcess) can call the WaitForDebugEvent function.
DEBUG_ONLY_THIS_PROCESS
	If not set and the calling process is being debugged, the new process becomes another process being debugged by the calling process's debugger. If the calling process is not a process being debugged, no debugging-related actions occur.
DETACHED_PROCESS
	For console processes, the new process does not have access to the console of the parent process. The new process can call the AllocConsole function at a later time to create a new console. This flag cannot be used with the CREATE_NEW_CONSOLE flag.
The dwCreationFlags parameter also controls the new process's priority class, which is used in determining the scheduling priorities of the process's threads. If none of the following priority class flags is specified, the priority class defaults to NORMAL_PRIORITY_CLASS unless the priority class of the creating process is IDLE_PRIORITY_CLASS. In this case the default priority class of the child process is IDLE_PRIORITY_CLASS. One of the following flags can be specified:

Priority	Meaning
HIGH_PRIORITY_CLASS	Indicates a process that performs time-critical tasks that must be executed immediately for it to run correctly. The threads of a high-priority class process preempt the threads of normal-priority or idle-priority class processes. An example is Windows Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all available cycles.
IDLE_PRIORITY_CLASS	Indicates a process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS	Indicates a normal process with no special scheduling needs.
REALTIME_PRIORITY_CLASS	Indicates a process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
lpEnvironment

Points to an environment block for the new process. If this parameter is NULL, the new process uses the environment of the calling process.

An environment block consists of a null-terminated block of null-terminated strings. Each string is in the form:

name=value

Because the equal sign is used as a separator, it must not be used in the name of an environment variable.

If an application provides an environment block, rather than passing NULL for this parameter, the current directory information of the system drives is not automatically propagated to the new process. For a discussion of this situation and how to handle it, see the following Remarks section.

An environment block can contain Unicode or ANSI characters. If the environment block pointed to by lpEnvironment contains Unicode characters, the dwCreationFlags field's CREATE_UNICODE_ENVIRONMENT flag will be set. If the block contains ANSI characters, that flag will be clear.

Note that an ANSI environment block is terminated by two zero bytes: one for the last string, one more to terminate the block. A Unicode environment block is terminated by four zero bytes: two for the last string, two more to terminate the block.

lpCurrentDirectory

Points to a null-terminated string that specifies the current drive and directory for the new process. The string must be a full path and filename that includes a drive letter. If this parameter is NULL, the new process is created with the same current drive and directory as the calling process. This option is provided primarily for shells that need to start an application and specify its initial drive and working directory.

lpStartupInfo

Points to a STARTUPINFO structure that specifies how the main window for the new process should appear.

lpProcessInformation

Points to a PROCESS_INFORMATION structure that receives identification information about the new process.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The CreateProcess function is used to run a new program. The WinExec and LoadModule functions are still available, but they are implemented as calls to CreateProcess.

In addition to creating a process, CreateProcess also creates a thread object. The thread is created with an initial stack whose size is described in the image header of the specified program's executable file. The thread begins execution at the image's entry point.

The new process and the new thread handles are created with full access rights. For either handle, if a security descriptor is not provided, the handle can be used in any function that requires an object handle of that type. When a security descriptor is provided, an access check is performed on all subsequent uses of the handle before access is granted. If the access check denies access, the requesting process is not able to use the handle to gain access to the thread.

The process is assigned a 32-bit process identifier. The 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 lpApplicationName or lpCommandLine strings, it doesn't matter whether the application name includes the filename extension, with one exception: an MS-DOS − based or Windows-based application whose filename extension is .COM must include the .COM extension.

The calling thread can use the WaitForInputIdle function to wait until the new process has finished its initialization and is waiting for user input with no input pending. This can be useful for synchronization between parent and child processes, because CreateProcess returns without waiting for the new process to finish its initialization. For example, the creating process would use WaitForInputIdle before trying to find a window associated with the new process.

The preferred way to shut down a process is by using the ExitProcess function, because this function notifies all dynamic-link libraries (DLLs) attached to the process of the approaching termination. Other means of shutting down a process do not notify the attached DLLs. Note that when a thread calls ExitProcess, other threads of the process are terminated without an opportunity to execute any additional code (including the thread termination code of attached DLLs).

ExitProcess, ExitThread, CreateThread, CreateRemoteThread, and a process that is starting (as the result of a call by CreateProcess) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	The ExitProcess function does not return until no threads are in their DLL initialization or detach routines.

The created process remains in the system until all threads within the process have terminated and all handles to the process and any of its threads have been closed through calls to CloseHandle. The handles for both the process and the main thread must be closed through calls to CloseHandle. If these handles are not needed, it is best to close them immediately after the process is created.

When the last thread in a process terminates, the following events occur:

•	All objects opened by the process are implicitly closed.

•	The process's termination status (which is returned by GetExitCodeProcess) changes from its initial value of STILL_ACTIVE to the termination status of the last thread to terminate.

•	The thread object of the main thread is set to the signaled state, satisfying any threads that were waiting on the object.

•	The process object is set to the signaled state, satisfying any threads that were waiting on the object.

If the current directory on drive C is \MSVC\MFC, there is an environment variable called =C: whose value is C:\MSVC\MFC. As noted in the previous description of lpEnvironment, such current directory information for a system's drives does not automatically propagate to a new process when the CreateProcess function's lpEnvironment parameter is non-NULL. An application must manually pass the current directory information to the new process. To do so, the application must explicitly create the =X environment variable strings, get them into alphabetical order (because Windows NT and Windows 95 use a sorted environment), and then put them into the environment block specified by lpEnvironment. Typically, they will go at the front of the environment block, due to the previously mentioned environment block sorting.

One way to obtain the current directory variable for a drive X is to call GetFullPathName("X:",. .). That avoids an application having to scan the environment block. If the full path returned is X:\, there is no need to pass that value on as environment data, since the root directory is the default current directory for drive X of a new process.

The handle returned by the CreateProcess function has PROCESS_ALL_ACCESS access to the process object.

When a process is created with CREATE_NEW_PROCESS_GROUP specified, an implicit call to SetConsoleCtrlHandler(NULL,TRUE) is made on behalf of the new process; this means that the new process has Ctrl-C disabled. This lets good shells handle Ctrl-C themselves, and selectively pass that signal on to sub-processes. Ctrl-BREAK is not disabled, and may be used to interrupt the process/process group.

See Also

AllocConsole, CloseHandle, CreateRemoteThread, CreateThread, ExitProcess, ExitThread, GenerateConsoleCtrlEvent, GetCommandLine, GetEnvironmentStrings, GetExitCodeProcess, GetFullPathName, GetStartupInfo, GetSystemDirectory, GetWindowsDirectory, LoadModule, OpenProcess, PROCESS_INFORMATION, ResumeThread, SECURITY_ATTRIBUTES, SetConsoleCtrlHandler, SetErrorMode, STARTUPINFO, TerminateProcess, WaitForInputIdle, WaitForDebugEvent, WinExec


CreateProcessAsUser  (preliminaryWindows NT)
 CreateProcessAsUser  (preliminary−Windows NT)

The CreateProcessAsUser function creates a new process and its primary thread. The new process then executes a specified executable file. The CreateProcessAsUser function behaves just like the CreateProcess function, with one important difference: the created process runs in a context in which the system sees the user represented by the hToken parameter as if that user had logged on to the system and then called the CreateProcess function.

BOOL CreateProcessAsUser(

HANDLE hToken	// handle to a token that represents a logged-on user
LPCTSTR  lpApplicationName,	// pointer to name of executable module
LPTSTR  lpCommandLine,	// pointer to command line string
LPSECURITY_ATTRIBUTES  lpProcessAttributes,	// pointer to process security attributes
LPSECURITY_ATTRIBUTES  lpThreadAttributes,	// pointer to thread security attributes
BOOL  bInheritHandles,	// new process inherits handles
DWORD  dwCreationFlags,	// creation flags
LPVOID  lpEnvironment,	// pointer to new environment block
LPCTSTR  lpCurrentDirectory,	// pointer to current directory name
LPSTARTUPINFO  lpStartupInfo,	// pointer to STARTUPINFO
LPPROCESS_INFORMATION  lpProcessInformation	// pointer to PROCESS_INFORMATION
);
Parameters

hToken

Handle to a token that represents a user. You obtain such a token by calling the LogonUser function. The user represented by the token must have read and execute access to the application specified by the lpApplicationName or the lpCommandLine parameter.

The other parameters of the CreateProcessAsUser function behave just like the analogous parameters of the CreateProcess function.

lpApplicationName

Points to a null-terminated string specifying the full path and filename of the module to execute. If a partial name is specified, the current drive and current directory are used by default. If this parameter is NULL, the module name must be the first white space-delimited token in the lpCommandLine string. The specified module can be a Win32-based application, or it can be some other type of module (for example, MS-DOS or OS/2) if the appropriate subsystem is available on the local computer.

lpCommandLine

Points to a null-terminated string specifying the command line for the application to be executed. If this parameter is NULL, the lpApplicationName string is used as the command line. If both lpApplicationName and lpCommandLine are non-NULL, lpApplicationName specifies the module to execute and lpCommandLine is used as the command line. The new process can use GetCommandLine to retrieve the entire command line; or C runtime processes can use the argc/argv mechanism.

If lpApplicationName is NULL, the first white space-delimited token of the command line specifies the module name. If the filename does not contain an extension, .EXE is assumed. If the filename ends in a period (.) with no extension, or the filename contains a path, .EXE is not appended. If the filename does not contain a directory path, Windows searches for the executable file in the following sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT only: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

If the process to be created is an MS-DOS − based or Windows-based application, lpCommandLine should be a full command line in which the first element is the application name. Because this also works well for Win32-based applications, it is the most robust way to set lpCommandLine.

lpProcessAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the created process.

If lpProcessAttributes is NULL, the process is created with a default security descriptor, and the resulting handle is not inherited.

lpThreadAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the primary thread of the new process. If lpThreadAttributes is NULL, the process is created with a default security descriptor, and the resulting handle is not inherited.

bInheritHandles

Indicates whether the new process inherits handles from the calling process. If TRUE, each inheritable open handle in the calling process is inherited by the new process. Inherited handles have the same value and access privileges as the original handles.

dwCreationFlags

Specifies additional flags that control the priority class and the creation of the process. The following creation flags can be specified in any combination, except as noted:

Value	Meaning
CREATE_DEFAULT_ERROR_MODE
	The new process does not inherit the error mode of the calling process. Instead, CreateProcessAsUser gives the new process the current default error mode. An application sets the current default error mode by calling SetErrorMode. This flag is particularly useful for multi-threaded shell applications that run with hard errors disabled.  The default behavior for CreateProcessAsUser is for the new process to inherit the error mode of the caller. Setting this flag changes that default behavior.
CREATE_NEW_CONSOLE
	The new process has a new console, instead of inheriting the parent's console. This flag cannot be used with the DETACHED_PROCESS flag.
CREATE_NEW_PROCESS_GROUP
	The new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. The process ID of the new process group is the same as the process ID, which is returned in the lpProcessInformation parameter. Process groups are used by the GenerateConsoleCtrlEvent function to enable sending a CTRL+C or CTRL+BREAK signal to a group of console processes.
CREATE_SEPARATE_WOW_VDM
	This flag is only valid only launching a 16-bit Windows program.  If set, the new process is run in a private Virtual DOS Machine (VDM).  By default, all 16-bit Windows programs are run in a single, shared VDM.  The advantage of running separately is that a crash only kills the single VDM; any other programs running in distinct VDMs continue to function normally.  Also, 16-bit Windows applications which are run in separate VDMs have separate input queues. That means that if one application hangs momentarily, applications in separate VDMs continue to receive input.
CREATE_SUSPENDED
	The primary thread of the new process is created in a suspended state, and does not run until the ResumeThread function is called.
CREATE_UNICODE_ENVIRONMENT
	If set, the environment block pointed to by lpEnvironment uses Unicode characters. If clear, the environment block uses ANSI characters.
DEBUG_PROCESS
	If set, the calling process is treated as a debugger, and the new process is a process being debugged. The system notifies the debugger of all debug events that occur in the process being debugged.
DEBUG_ONLY_THIS_PROCESS
	If not set and the calling process is being debugged, the new process becomes another process being debugged by the calling process's debugger. If the calling process is not a process being debugged, no debugging-related actions occur.
DETACHED_PROCESS
	For console processes, the new process does not have access to the console of the parent process. The new process can call the AllocConsole function at a later time to create a new console. This flag cannot be used with the CREATE_NEW_CONSOLE flag.
The dwCreationFlags parameter also controls the new process's priority class, which is used in determining the scheduling priorities of the process's threads. If none of the following priority class flags is specified, the priority class defaults to NORMAL_PRIORITY_CLASS unless the priority class of the creating process is IDLE_PRIORITY_CLASS. In this case the default priority class of the child process is IDLE_PRIORITY_CLASS. One of the following flags can be specified:

Priority	Meaning
HIGH_PRIORITY_CLASS	Indicates a process that performs time-critical tasks that must be executed immediately for it to run correctly. The threads of a high-priority class process preempt the threads of normal-priority or idle-priority class processes. An example is Windows Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all available cycles.
IDLE_PRIORITY_CLASS	Indicates a process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS	Indicates a normal process with no special scheduling needs.
REALTIME_PRIORITY_CLASS	Indicates a process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
lpEnvironment

Points to an environment block for the new process. If this parameter is NULL, the new process uses the environment of the calling process.

An environment block consists of a null-terminated block of null-terminated strings. Each string is in the form:

name=value

Because the equal sign is used as a separator, it must not be used in the name of an environment variable.

If an application provides an environment block, rather than passing NULL for this parameter, the current directory information of the system drives is not automatically propagated to the new process. For a discussion of this situation and how to handle it, see the following Remarks section.

An environment block can contain Unicode or ANSI characters. If the environment block pointed to by lpEnvironment contains Unicode characters, the dwCreationFlags field's CREATE_UNICODE_ENVIRONMENT flag will be set. If the block contains ANSI characters, that flag will be clear.

Note that an ANSI environment block is terminated by two zero bytes: one for the last string, one more to terminate the block. A Unicode environment block is terminated by four zero bytes: two for the last string, two more to terminate the block.

lpCurrentDirectory

Points to a null-terminated string that specifies the current drive and directory for the new process. The string must be a full path and filename that includes a drive letter. If this parameter is NULL, the new process is created with the same current drive and directory as the calling process. This option is provided primarily for shells that need to start an application and specify its initial drive and working directory.

lpStartupInfo

Points to a STARTUPINFO structure that specifies how the main window for the new process should appear.

lpProcessInformation

Points to a PROCESS_INFORMATION structure that receives identification information about the new process.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The calling process must have the SeAssignPrimary privilege. If it does not, the call to CreateProcessAsUser will fail.

In addition to creating a process, CreateProcessAsUser also creates a thread object. The thread is created with an initial stack whose size is described in the image header of the specified program's executable file. The thread begins execution at the image's entry point.

The new process and the new thread handles are created with full access rights. For either handle, if a security descriptor is not provided, the handle can be used in any function that requires an object handle of that type. When a security descriptor is provided, an access check is performed on all subsequent uses of the handle before access is granted. If the access check denies access, the requesting process is not able to use the handle to gain access to the thread.

The process is assigned a 32-bit process identifier. The 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 lpApplicationName or lpCommandLine strings, it doesn't matter whether the application name includes the filename extension, with one exception: an MS-DOS − based or Windows-based application whose filename extension is .COM must include the .COM extension.

The calling thread can use the WaitForInputIdle function to wait until the new process has finished its initialization and is waiting for user input with no input pending. This can be useful for synchronization between parent and child processes, because CreateProcessAsUser returns without waiting for the new process to finish its initialization. For example, the creating process would use WaitForInputIdle before trying to find a window associated with the new process.

The preferred way to shut down a process is by using the ExitProcess function, because this function notifies all dynamic-link libraries (DLLs) attached to the process of the approaching termination. Other means of shutting down a process do not notify the attached DLLs. Note that when a thread calls ExitProcess, other threads of the process are terminated without an opportunity to execute any additional code (including the thread termination code of attached DLLs).

ExitProcess, ExitThread, CreateThread, CreateRemoteThread, and a process that is starting (as the result of a call by CreateProcessAsUser) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	The ExitProcess function does not return until no threads are in their DLL initialization or detach routines.

The created process remains in the system until all threads within the process have terminated and all handles to the process and any of its threads have been closed through calls to CloseHandle. The handles for both the process and the main thread must be closed through calls to CloseHandle. If these handles are not needed, it is best to close them immediately after the process is created.

When the last thread in a process terminates, the following events occur:

•	All objects opened by the process are implicitly closed.

•	The process's termination status (which is returned by GetExitCodeProcess) changes from its initial value of STILL_ACTIVE to the termination status of the last thread to terminate.

•	The thread object of the main thread is set to the signaled state, satisfying any threads that were waiting on the object.

•	The process object is set to the signaled state, satisfying any threads that were waiting on the object.

If the current directory on drive C is \MSVC\MFC, there is an environment variable called =C: whose value is C:\MSVC\MFC. As noted in the previous description of lpEnvironment, such current directory information for a system's drives does not automatically propagate to a new process when the CreateProcessAsUser function's lpEnvironment parameter is non-NULL. An application must manually pass the current directory information to the new process. To do so, the application must explicitly create the =X environment variable strings, get them into alphabetical order (because Windows NT uses a sorted environment), and then put them into the environment block specified by lpEnvironment. Typically, they will go at the front of the environment block, due to the previously mentioned Windows NT environment block sorting.

One way to obtain the current directory variable for a drive X is to call GetFullPathName("X:",. .). That avoids an application having to scan the environment block. If the full path returned is X:\, there is no need to pass that value on as environment data, since the root directory is the default current directory for drive X of a new process.

The handle returned by the CreateProcessAsUser 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, CreateProcess, CreateRemoteThread, CreateThread, ExitProcess, ExitThread, GenerateConsoleCtrlEvent, GetCommandLine, GetEnvironmentStrings, GetExitCodeProcess, GetFullPathName, GetStartupInfo, GetSystemDirectory, GetWindowsDirectory, ImpersonateLoggedOnUser, LoadModule, LogonUser, OpenProcess, PROCESS_INFORMATION, ResumeThread, SECURITY_ATTRIBUTES, SetConsoleCtrlHandler, SetErrorMode, STARTUPINFO, TerminateProcess, WaitForInputIdle, WinExec


CreatePropertySheetPage  (preliminaryWindows NT)
 CreatePropertySheetPage  (preliminary−Windows NT)

The CreatePropertySheetPage function creates a new page for a property sheet.

HPROPSHEETPAGE CreatePropertySheetPage(

LPCPROPSHEETPAGE  lppsp
);
Parameters

lppsp

Pointer to a PROPSHEETPAGE structure that defines a page to be included in a property sheet.

Return Value

If the function succeeds, the return value is the handle to the new property sheet.

If the function fails, the return value is NULL.

Remarks

An application uses the PropertySheet function to create a property sheet that includes the new page or uses the PSM_ADDPAGE message to add the new page to an existing property sheet.

PropertySheet, PROPSHEETPAGE, PSM_ADDPAGE


 CreateRectRgn

The CreateRectRgn function creates a rectangular region.

HRGN CreateRectRgn(

int  nLeftRect,	// x-coordinate of region's upper-left corner
int  nTopRect,	// y-coordinate of region's upper-left corner
int  nRightRect,	// x-coordinate of region's lower-right corner
int  nBottomRect	// y-coordinate of region's lower-right corner
);
Parameters

nLeftRect

Specifies the x-coordinate of the upper-left corner of the region.

nTopRect

Specifies the y-coordinate of the upper-left corner of the region.

nRightRect

Specifies the x-coordinate of the lower-right corner of the region.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the region.

Return Value

If the function succeeds, the return value is the handle of the region.

If the function fails, the return value is NULL.

Remarks

The region will be exclusive of the bottom and right edges.

See Also

CreateRectRgnIndirect, CreateRoundRectRgn, DeleteObject, SelectObject


 CreateRectRgnIndirect

The CreateRectRgnIndirect function creates a rectangular region.

HRGN CreateRectRgnIndirect(

CONST RECT  *lprc	// address of the rectangle
);
Parameters

lprc

Points to a RECT structure that contains the coordinates of the upper-left and lower-right corners of the rectangle that defines the region.

Return Value

If the function succeeds, the return value is the handle of the region.

If the function fails, the return value is NULL.

Remarks

The region will be exclusive of the bottom and right edges.

See Also

CreateRectRgn, CreateRoundRectRgn, DeleteObject, RECT, SelectObject


 CreateRemoteThread

The CreateRemoteThread function creates a thread that runs in the address space of another process.

HANDLE CreateRemoteThread(

HANDLE  hProcess,	// handle to process to create thread in
LPSECURITY_ATTRIBUTES  lpThreadAttributes,	// address of thread security attributes
DWORD  dwStackSize,	// initial thread stack size, in bytes
LPTHREAD_START_ROUTINE  lpStartAddress,	// address of thread function
LPVOID  lpParameter,	// address of argument for new thread
DWORD  dwCreationFlags,	// creation flags
LPDWORD  lpThreadId	// address of returned thread identifier
);
Parameters

hProcess

Identifies the process in which the thread is to be created. The handle must have PROCESS_CREATE_THREAD access.

lpThreadAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the thread.

If lpThreadAttributes is NULL, the thread is created with a default security descriptor, and the resulting handle is not inherited.

dwStackSize

Specifies the size, in bytes, of the stack for the new thread. If this value is zero, the stack size defaults to the same size as that of the primary thread of the process. The stack is allocated automatically in the memory space of the process and is freed when the thread terminates. Note that the stack size grows as necessary.

lpStartAddress

Points to the starting address of the new thread. The address is logically a procedure that never returns and that accepts a single 32-bit pointer as an argument.

lpParameter

Points to a single 32-bit value passed to the thread.

dwCreationFlags

Specifies additional flags that control the creation of the thread. If the CREATE_SUSPENDED flag is specified, the thread is created in a suspended state and will not run until the ResumeThread function is called. If this value is zero, the thread runs immediately after creation.

lpThreadId

Points to a 32-bit variable that receives the thread identifier.

Return Value

If the function succeeds, the return value is a handle to the new thread.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

CreateRemoteThread causes a new thread of execution to begin in the address space of the specified process. The thread has access to all objects opened by the process.

The new thread handle is created with full access to the new thread. If a security descriptor is not provided, the handle may be used in any function that requires a thread object handle. When a security descriptor is provided, an access check is performed on all subsequent uses of the handle before access is granted. If the access check denies access, the requesting process cannot use the handle to gain access to the thread.

The thread execution begins at the function specified by the lpStartAddress parameter. If this function returns, the results are unspecified.

CreateRemoteThread may succeed even if lpStartAddress points to data, code, or is not accessible. If the start address is invalid when the thread runs, an exception occurs, and the thread terminates. Thread termination due to a invalid start address is handled as an error exit for the thread's process. This behavior is similar to the asynchronous nature of CreateProcess, where the process is created even if it refers to invalid or missing dynamic-link libraries (DLLs).

The thread is created with a thread priority of THREAD_PRIORITY_NORMAL. Use the GetThreadPriority and SetThreadPriority functions to get and set the priority value of a thread.

When a thread terminates, the thread object attains a signaled state, satisfying any threads that were waiting for the object.

The thread object remains in the system until the thread has terminated and all handles to it have been closed through a call to CloseHandle.

The ExitProcess, ExitThread, CreateThread, CreateRemoteThread functions, and a process that is starting (as the result of a CreateProcess call) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	ExitProcess does not return until no threads are in their DLL initialization or detach routines.

See Also

CloseHandle, CreateProcess, CreateThread, ExitProcess, ExitThread, GetThreadPriority, ResumeThread, SECURITY_ATTRIBUTES, SetThreadPriority


 CreateRoundRectRgn

The CreateRoundRectRgn function creates a rectangular region with rounded corners.

HRGN CreateRoundRectRgn(

int  nLeftRect,	// x-coordinate of the region's  upper-left corner
int  nTopRect,	// y-coordinate of the region's upper-left corner
int  nRightRect,	// x-coordinate of the region's lower-right corner
int  nBottomRect,	// y-coordinate of the region's lower-right corner
int  nWidthEllipse,	// height of ellipse for rounded corners
int  nHeightEllipse	// width of ellipse for rounded corners
);
Parameters

nLeftRect

Specifies the x-coordinate of the upper-left corner of the region.

nTopRect

Specifies the y-coordinate of the upper-left corner of the region.

nRightRect

Specifies the x-coordinate of the lower-right corner of the region.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the region.

nWidthEllipse

Specifies the width of the ellipse used to create the rounded corners.

nHeightEllipse

Specifies the height of the ellipse used to create the rounded corners.

Return Value

If the function succeeds, the return value is the handle of the region.

If the function fails, the return value is NULL.

See Also

CreateRectRgn, CreateRectRgnIndirect, DeleteObject, SelectObject


 CreateScalableFontResource

The CreateScalableFontResource function creates a font resource file for a scalable font.

BOOL CreateScalableFontResource(

DWORD  fdwHidden,	// flag for read-only embedded font
LPCTSTR  lpszFontRes,	// address of filename for font resource
LPCTSTR  lpszFontFile,	// address of filename for scalable font
LPCTSTR  lpszCurrentPath	// address of path to font file
);
Parameters

fdwHidden

Specifies whether the font is a read-only embedded font. This parameter can be one of the following values:

Value	Meaning
0	The font has read-write permission.
1	The font has read-only permission and should be hidden from other applications in the system. When this flag is set, the font is not enumerated by the EnumFonts or EnumFontFamilies function.
lpszFontRes

Points to a null-terminated string specifying the name of the font resource file that this function creates.

lpszFontFile

Points to a null-terminated string specifying the name of the scalable font file that this function uses to create the font resource file.

lpszCurrentPath

Points to a null-terminated string specifying the path to the scalable font file.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The CreateScalableFontResource function is used by applications that install TrueType fonts. An application uses the CreateScalableFontResource function to create a font resource file (typically with a .FOT filename extension) and then uses the AddFontResource function to install the font. The TrueType font file (typically with a .TTF filename extension) must be in the SYSTEM subdirectory of the WINDOWS directory to be used by the AddFontResource function.

The CreateScalableFontResource function currently supports only TrueType-technology scalable fonts.

When the lpszFontFile parameter specifies only a filename and extension, the lpszCurrentPath parameter must specify a path. When the lpszFontFile parameter specifies a full path, the lpszCurrentPath parameter must be NULL or a pointer to NULL.

When only a filename and extension are specified in the lpszFontFile parameter and a path is specified in the lpszCurrentPath parameter, the string in lpszFontFile is copied into the .FOT file as the .TTF file that belongs to this resource. When the AddFontResource function is called, the operating system assumes that the .TTF file has been copied into the SYSTEM directory (or into the main Windows directory in the case of a network installation). The .TTF file need not be in this directory when the CreateScalableFontResource function is called, because the lpszCurrentPath parameter contains the directory information. A resource created in this manner does not contain absolute path information and can be used in any Windows installation.

When a path is specified in the lpszFontFile parameter and NULL is specified in the lpszCurrentPath parameter, the string in lpszFontFile is copied into the .FOT file. In this case, when the AddFontResource function is called, the .TTF file must be at the location specified in the lpszFontFile parameter when the CreateScalableFontResource function was called; the lpszCurrentPath parameter is not needed. A resource created in this manner contains absolute references to paths and drives and does not work if the .TTF file is moved to a different location.

See Also

AddFontResource, EnumFonts, EnumFontFamilies


 CreateSemaphore

The CreateSemaphore function creates a named or unnamed semaphore object.

HANDLE CreateSemaphore(

LPSECURITY_ATTRIBUTES  lpSemaphoreAttributes,	// address of security attributes
LONG  lInitialCount,	// initial count
LONG  lMaximumCount,	// maximum count
LPCTSTR  lpName	// address of semaphore-object name
);
Parameters

lpSemaphoreAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the semaphore object.

If lpSemaphoreAttributes is NULL, the semaphore object is created with a default security descriptor and the resulting handle is not inheritable.

lInitialCount

Specifies an initial count for the semaphore object. This value must be greater than or equal to zero and less than or equal to lMaximumCount. The state of a semaphore is signaled when its count is greater than zero and nonsignaled when it is zero. The count is decreased by one whenever a wait function releases a thread that was waiting for the semaphore. The count is increased by a specified amount by calling the ReleaseSemaphore function.

lMaximumCount

Specifies the maximum count for the semaphore object. This value must be greater than zero.

lpName

Points to a null-terminated string specifying the name of the semaphore object. The name is limited to MAX_PATH characters, and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive.

If lpName matches the name of an existing named semaphore object, this function requests SEMAPHORE_ALL_ACCESS access to the existing object. In this case, the lInitialCount and lMaximumCount parameters are ignored because they have already been set by the creating process. If the lpSemaphoreAttributes parameter is not NULL, it determines whether the handle can be inherited, but its security-descriptor member is ignored.

If lpName is NULL, the semaphore object is created without a name.

If lpName matches the name of an existing event, mutex, or file-mapping object, the function fails and the GetLastError function returns ERROR_INVALID_HANDLE. This occurs because event, mutex, semaphore, and file-mapping objects share the same name space.

Return Value

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, call GetLastError.

Remarks

The handle returned by CreateSemaphore has SEMAPHORE_ALL_ACCESS access to the new semaphore object and can be used in any function that requires a handle 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 lInitialCount parameter specifies the initial count. Each time a waiting thread is released because of the semaphore's signaled state, the count of the semaphore is decreased by one. Use the ReleaseSemaphore function to increment a semaphore's count by a specified amount. The count can never be less than zero or greater than the value specified in the lMaximumCount parameter.

Multiple processes can have handles of the same semaphore object, enabling use of the object for interprocess synchronization. The following object-sharing mechanisms are available:

•	A child process created by the CreateProcess function can inherit a handle of a semaphore object if the lpSemaphoreAttributes parameter of CreateSemaphore enabled inheritance.

•	A process can specify the semaphore-object handle in a call to the DuplicateHandle function to create a duplicate handle that can be used by another process.

•	A process can specify the name of a semaphore object in a call to the OpenSemaphore or CreateSemaphore function.

Use the CloseHandle function to close the handle. The system closes the handle automatically when the process terminates. The semaphore object is destroyed when its last handle has been closed.

See Also

CloseHandle, CreateProcess, DuplicateHandle, OpenSemaphore, ReleaseSemaphore, SECURITY_ATTRIBUTES, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


 CreateService

The CreateService function creates a service object and adds it to the specified service control manager database.

SC_HANDLE CreateService(

SC_HANDLE  hSCManager,	// handle of service control manager database
LPCTSTR  lpServiceName,	// address of name of service to start
LPCTSTR  lpDisplayName,	// address of display name
DWORD  dwDesiredAccess,	// type of access to service
DWORD  dwServiceType,	// type of service
DWORD  dwStartType,	// when to start service
DWORD  dwErrorControl,	// severity if service fails to start
LPCTSTR  lpBinaryPathName,	// address of name of binary file
LPCTSTR  lpLoadOrderGroup,	// address of name of load ordering group
LPDWORD  lpdwTagId,	// address of variable to get tag identifier
LPCTSTR  lpDependencies,	// address of array of dependency names
LPCTSTR  lpServiceStartName,	// address of account name of service
LPCTSTR  lpPassword	// address of password for service account
);
Parameters

hSCManager

Identifies the service control manager database. The OpenSCManager function returns this handle which must have SC_MANAGER_CREATE_SERVICE access.

lpServiceName

Points to a null-terminated string that names the service to install. The maximum string length is 256 characters. The service control manager database preserves the case of the characters, but service name comparisons are always case insensitive. Forward-slash (/) and back-slash (\) are invalid service name characters.

lpDisplayName

Points to a null-terminated string that is to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the service control manager. Display name comparisons are always case-insensitive.

dwDesiredAccess

Specifies the access to the service. Before granting the requested access, the system checks the access token of the calling process. Any or all of the following service object access types can be specified:

Access	Description
SERVICE_ALL_ACCESS	Includes STANDARD_RIGHTS_REQUIRED in addition to all of the access types listed in this table.
SERVICE_CHANGE_CONFIG	Enables calling of the ChangeServiceConfig function to change the service configuration.
SERVICE_ENUMERATE_DEPENDENTS	Enables calling of the EnumDependentServices function to enumerate all the services dependent on the service.
SERVICE_INTERROGATE	Enables calling of the ControlService function to ask the service to report its status immediately.
SERVICE_PAUSE_CONTINUE	Enables calling of the ControlService function to pause or continue the service.
SERVICE_QUERY_CONFIG	Enables calling of the QueryServiceConfig function to query the service configuration.
SERVICE_QUERY_STATUS	Enables calling of the QueryServiceStatus function to ask the service control manager about the status of the service.
SERVICE_START	Enables calling of the StartService function to start the service.
SERVICE_STOP	Enables calling of the ControlService function to stop the service.
SERVICE_USER_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 dwDesiredAccess parameter can specify any or all of the following generic access types:

Generic access	Service access
GENERIC_READ	Combines the following accesses: STANDARD_RIGHTS_READ, SERVICE_QUERY_CONFIG, SERVICE_QUERY_STATUS, and SERVICE_ENUMERATE_DEPENDENTS.
GENERIC_WRITE	Combines the following accesses: STANDARD_RIGHTS_WRITE and SERVICE_CHANGE_CONFIG.
GENERIC_EXECUTE	Combines the following accesses: STANDARD_RIGHTS_EXECUTE, SERVICE_START, SERVICE_STOP, SERVICE_PAUSE_CONTINUE, SERVICE_INTERROGATE, and SERVICE_USER_DEFINED_CONTROL.
dwServiceType

A set of bit flags that specify the type of service. You must specify one of the following service type flags to indicate the service type. In addition, if you specify either of the SERVICE_WIN32 flags, you can also specify the SERVICE_INTERACTIVE_PROCESS flag to enable the service process to interact with the desktop.

Value	Meaning
SERVICE_WIN32_OWN_PROCESS	A service-type flag that specifies a Win32 service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS	A service-type flag that specifies a Win32 service that shares a process with other services.
SERVICE_KERNEL_DRIVER	A service-type flag that specifies a Windows NT device driver.
SERVICE_FILE_SYSTEM_DRIVER	A service-type flag that specifies a Windows NT file system driver.
SERVICE_INTERACTIVE_PROCESS	A flag that enables a Win32 service process to interact with the desktop.
dwStartType

Specifies when to start the service. This member can be one of the following values:

Value	Meaning
SERVICE_BOOT_START	Specifies a device driver started by the operating system loader. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_SYSTEM_START	Specifies a device driver started by the IoInitSystem function. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_AUTO_START	Specifies a device driver or Win32 service started by the service control manager automatically during system startup.
SERVICE_DEMAND_START	Specifies a device driver or Win32 service started by the service control manager when a process calls the StartService function.
SERVICE_DISABLED	Specifies a device driver or Win32 service that can no longer be started.
dwErrorControl

Specifies the severity of the error if this service fails to start during startup, and determines the action taken by the startup program if failure occurs. One of the following values can be specified:

Value	Meaning
SERVICE_ERROR_IGNORE	The startup (boot) program logs the error but continues the startup operation.
SERVICE_ERROR_NORMAL	The startup program logs the error and displays a message but continues the startup operation.
SERVICE_ERROR_SEVERE	The startup program logs the error. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.
SERVICE_ERROR_CRITICAL	The startup program logs the error, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known-good configuration.
lpBinaryPathName

Points to a null-terminated string that contains the fully qualified path to the service binary file.

lpLoadOrderGroup

Points to a null-terminated string that names the load ordering group of which this service is a member. If the pointer is NULL or if it points to an empty string, the service does not belong to a group. The registry has a list of load ordering groups located at:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control
\ServiceGroupOrder.

The startup program uses this list to load groups of services in a specified order with respect to the other groups in the list. You can place a service in a group so that another service can depend on the group.

The order in which a service starts is determined by the following criteria:

1.	The order of groups in the registry's load-ordering group list. Services in groups in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list and then services that do not belong to a group.

2.	The service's dependencies listed in the lpDependencies parameter and the dependencies of other services dependent on the service.

lpdwTagId

Points to a 32-bit variable that receives a unique tag value for this service in the group specified in the lpLoadOrderGroup parameter. If no tag is requested, this parameter can be NULL.

You can use a tag for ordering service startup in a load ordering group by specifying a tag order vector in the registry located at:

HKEY_LOCAL_MACHINE\System\ CurrentControlSet
\Control\GroupOrderList.

Tags are only evaluated for SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER type services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

lpDependencies

Points to an array of null-separated names of services or load ordering groups that must start before this service. The array is double null-terminated. If the pointer is NULL or if it points to an empty string, the service has no dependencies. If a group name is specified, it must be prefixed by the SC_GROUP_IDENTIFIER character (defined in the WINSVC.H file) to differentiate it from a service name, because services and service groups share the same name space. Dependency on a service means that this service can only run if the service it depends on is running. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.

lpServiceStartName

Points to a null-terminated string. If the service type is SERVICE_WIN32_OWN_PROCESS, this name is the account name in the form of "DomainName\Username", which the service process will be logged on as when it runs. If the account belongs to the built-in domain, ".\Username" can be specified. Services of type SERVICE_WIN32_SHARE_PROCESS are not allowed to specify an account other than LocalSystem. If NULL is specified, the service will be logged on as the "LocalSystem" account, in which case, the lpPassword parameter must be NULL.

If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this name is the Windows NT driver object name (that is, \FileSystem\Rdr or \Driver\Xns), which the input and output (I/O) system uses to load the device driver. If NULL is specified, the driver is run with a default object name created by the I/O system, based on the service name.

lpPassword

Points to a null-terminated string that contains the password to the account name specified by the lpServiceStartName parameter, if the service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS. If the pointer is NULL or if it points to an empty string, the service has no password. If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this parameter is ignored.

Return Value

If the function succeeds, the return value is a handle to the service.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Errors

The following error codes can be set by the service control manager. Other error codes can be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The handle to the specified service control manager database does not have SC_MANAGER_CREATE_SERVICE access.
ERROR_CIRCULAR_DEPENDENCY	A circular service dependency was specified.
ERROR_DUP_NAME	The display name already exists in the service control manager database either as a service name or as another display name.
ERROR_INVALID_HANDLE	The handle to the specified service control manager database is invalid.
ERROR_INVALID_NAME	The specified service name is invalid.
ERROR_INVALID_PARAMETER	A parameter that was specified is invalid.
ERROR_INVALID_SERVICE_ACCOUNT	The user account name specified in the lpServiceStartName parameter does not exist.
ERROR_SERVICE_EXISTS	The specified service already exists in this database.
Remarks

The CreateService function creates a service object and installs it in the service control manager database by creating a service name key in the registry with the following form:

HKEY_LOCAL_MACHINE\System\CurrentControlSet
\Services\lpServiceName

where lpServiceName is the service name specified for this function. Information specified for this function is saved as values under this key. Setup programs and the service itself can create any subkey under this service name key for any service specific information.

If the appropriate access rights are enabled, the calling process can use the returned handle to identify the newly created service in the following functions:

ChangeServiceConfig, ControlService, DeleteService, QueryServiceConfig, QueryServiceObjectSecurity, QueryServiceStatus, SetServiceObjectSecurity, StartService

The returned handle is only valid for the process that called CreateService. It can be closed by calling the CloseServiceHandle function.

See Also

ChangeServiceConfig, CloseServiceHandle, ControlService, DeleteService, EnumDependentServices, OpenSCManager, QueryServiceConfig, QueryServiceObjectSecurity, QueryServiceStatus, SetServiceObjectSecurity, StartService


 CreateSolidBrush

The CreateSolidBrush function creates a logical brush that has the specified solid color.

HBRUSH CreateSolidBrush(

COLORREF  crColor	// brush color value
);
Parameters

crColor

Specifies the color of the brush.

Return Value

If the function succeeds, the return value identifies a logical brush.

If the function fails, the return value is NULL.

Remarks

A solid brush is a bitmap that Windows uses to paint the interiors of filled shapes.

After an application creates a brush by calling CreateSolidBrush, it can select that brush into any device context by calling the SelectObject function.

See Also

CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateHatchBrush, CreatePatternBrush, DeleteObject, SelectObject


CreateStatusWindow  (preliminaryWindows NT)
 CreateStatusWindow  (preliminary−Windows NT)

The CreateStatusWindow function creates a status window, which is typically used to display the status of an application. The window generally appears at the bottom of the parent window, and it contains the specified text.

HWND CreateStatusWindow(

LONG style,
LPCTSTR lpszText,
HWND hwndParent,
UINT wID
);
Parameters

style

Window styles for the status window. This parameter must include the WS_CHILD style and should also include the WS_VISIBLE style.

lpszText

Pointer to a null-terminated string that specifies the status text for the first part.

hwndParent

Handle to the parent window.

wID

Control identifier for the status window. The window procedure uses this value to identify messages it sends to the parent window.

Return Value

If the function succeeds, the return value is the handle for the status window.

If the function fails, the return value is NULL.

Remarks

The CreateStatusWindow function calls the CreateWindow function to create the window. It passes the parameters to CreateWindow without modification and sets the position, width, and height parameters to default values.

See Also

CreateWindow


 CreateTapePartition

The CreateTapePartition function reformats a tape.

DWORD CreateTapePartition(

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
);
Parameters

hDevice

Identifies the device where the new partition is to be created. This handle is created by using the CreateFile function.

dwPartitionMethod

Specifies the type of partition to create. To determine what type of partitions your device supports, see the documentation for your hardware. This parameter can have one of the following values:

Value	Description
TAPE_FIXED_PARTITIONS	Partitions the tape based on the device's default definition of partitions. The dwCount and dwSize parameters are ignored.
TAPE_INITIATOR_PARTITIONS	Partitions the tape into the number and size of partitions specified by dwCount and dwSize, respectively, except for the last partition. The size of the last partition is the remainder of the tape.
TAPE_SELECT_PARTITIONS	Partitions the tape into the number of partitions specified by dwCount. The dwSize parameter is ignored. The size of the partitions is determined by the device's default partition size. For more specific information, refer to the documentation for your tape device.
dwCount

Specifies the number of partitions to create. The GetTapeParameters function provides the maximum number of partitions a tape can support.

dwSize

Specifies the size, in megabytes, of each partition. This value is ignored if the dwPartitionMethod parameter is TAPE_SELECT_PARTITIONS.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, it may return one of the following error codes:

Error	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

Creating partitions reformats the tape. All previous information recorded on the tape is destroyed.

See Also

CreateFile, GetTapeParameters


CreateToolbarEx  (preliminaryWindows NT)
 CreateToolbarEx  (preliminary−Windows NT)

The CreateToolbarEx function creates a toolbar window and adds the specified buttons to the toolbar.

HWND CreateToolbarEx(

HWND  hwnd,
DWORD  ws,
UINT  wID,
int  nBitmaps,
HINSTANCE  hBMInst,
UINT  wBMID,
LPCTBBUTTON  lpButtons,
int  iNumButtons,
int dxButton,
int dyButton,
int  dxBitmap,
int  dyBitmap,
UINT  uStructSize
);
Parameters

hwnd

Handle to the parent window for the toolbar.

ws

Window styles for the toolbar. This parameter must specify at least the WS_CHILD style.

wID

Control identifier for the toolbar.

nBitmaps

Number of button images contained in the bitmap specified by hBMInst and wBMID.

hBMInst

Module instance with the executable file that contains the bitmap resource.

wBMID

Resource identifier for the bitmap resource. If hBMInst is NULL, this parameter must be a valid bitmap handle.

lpButtons

Pointer to an array of TBBUTTON structures that contains information about the buttons to add to the toolbar.

iNumButtons

Number of buttons to add to the toolbar.

dxButton

Width, in pixels, of the buttons to add to the toolbar.

dyButton

Height, in pixels, of the buttons to add to the toolbar.

dxBitmap

Width, in pixels, of the button images to add to the buttons in the toolbar.

dyBitmap

Height, in pixels, of the button images to add to the buttons in the toolbar.

uStructSize

Size of a TBBUTTON structure.

Return Value

If the function succeeds, the return value is the window handle to the toolbarl

If the function fails, the return value is NULL.

See Also

TBBUTTON


 CreateThread

The CreateThread function creates a thread to execute within the address space of the calling process.

HANDLE CreateThread(

LPSECURITY_ATTRIBUTES  lpThreadAttributes,	// address of thread security attributes
DWORD  dwStackSize,	// initial thread stack size, in bytes
LPTHREAD_START_ROUTINE  lpStartAddress,	// address of thread function
LPVOID  lpParameter,	// argument for new thread
DWORD  dwCreationFlags,	// creation flags
LPDWORD  lpThreadId	// address of returned thread identifier
);
Parameters

lpThreadAttributes

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the thread.

If lpThreadAttributes is NULL, the thread is created with a default security descriptor, and the resulting handle is not inherited.

dwStackSize

Specifies the size, in bytes, of the stack for the new thread. If 0 is specified, the stack size defaults to the same size as that of the primary thread of the process. The stack is allocated automatically in the memory space of the process and it is freed when the thread terminates. Note that the stack size grows, if necessary.

lpStartAddress

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

lpParameter

Specifies a single 32-bit parameter value passed to the thread.

dwCreationFlags

Specifies additional flags that control the creation of the thread. If the CREATE_SUSPENDED flag is specified, the thread is created in a suspended state, and will not run until the ResumeThread function is called. If this value is zero, the thread runs immediately after creation.

lpThreadId

Points to a 32-bit variable that receives the thread identifier.

Return Value

If the function succeeds, the return value is a handle to the new thread.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Windows 95 only: CreateThread succeeds only when it is called in the context of a 32-bit program. A 32-bit DLL cannot create an additional thread when that DLL is being called by a 16-bit program.

Remarks

The new thread handle is created with full access to the new thread. If a security descriptor is not provided, the handle can be used in any function that requires a thread object handle. When a security descriptor is provided, an access check is performed on all subsequent uses of the handle before access is granted. If the access check denies access, the requesting process cannot use the handle to gain access to the thread.

The thread execution begins at the function specified by the lpStartAddress parameter. If this function returns, the DWORD return value is used to terminate the thread in an implicit call to the ExitThread function. Use the GetExitCodeThread function to get the thread's return value.

The CreateThread function may succeed even if lpStartAddress points to data, code, or is not accessible. If the start address is invalid when the thread runs, an exception occurs, and the thread terminates. Thread termination due to a invalid start address is handled as an error exit for the thread's process. This behavior is similar to the asynchronous nature of CreateProcess, where the process is created even if it refers to invalid or missing dynamic-link libraries (DLLs).

The thread is created with a thread priority of THREAD_PRIORITY_NORMAL. Use the GetThreadPriority and SetThreadPriority functions to get and set the priority value of a thread.

When a thread terminates, the thread object attains a signaled state, satisfying any threads that were waiting on the object.

The thread object remains in the system until the thread has terminated and all handles to it have been closed through a call to CloseHandle.

The ExitProcess, ExitThread, CreateThread, CreateRemoteThread functions, and a process that is starting (as the result of a call by CreateProcess) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means that the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	ExitProcess does not return until no threads are in their DLL initialization or detach routines.

A thread that uses functions from the C run-time libraries should use the beginthread and endthread C run-time functions for thread management rather than CreateThread and ExitThread. Failure to do so results in small memory leaks when ExitThread is called.

See Also

CloseHandle, CreateProcess, CreateRemoteThread, ExitProcess, ExitThread, GetExitCodeThread, GetThreadPriority, ResumeThread, SetThreadPriority, SECURITY_ATTRIBUTES


CreateUpDownControl  (preliminaryWindows NT)
 CreateUpDownControl  (preliminary−Windows NT)

The CreateUpDownControl function creates an up-down control.

HWND CreateUpDownControl(

DWORD  dwStyle,
int  x,
int  y,
int  cx,
int cy,
HWND  hParent,
int  nID,
HINSTANCE  hInst
HWND  hBuddy,
int  nUpper,
int  nLower,
int  nPos
);
Parameters

dwStyle

Window styles for the control. This parameter should include the WS_CHILD, WS_BORDER, and WS_VISIBLE styles, and it may include any of the window styles specific to the up-down control.

x

Horizontal coordinate, in client coordinates, of the upper-left corner of the control.

y

Vertical coordinate, in client coordinates, of the upper-left corner of the control.

cx

Width, in pixels, of the up-down control.

cy

Height, in pixels, of the up-down control.

hParent

Handle to the parent window of the up-down control

nID

Identifier for the up-down control.

hInst

Handle to the module instance of the application creating the up-down control.

hBuddy

Handle to the window associated with the up-down control. If this parameter is NULL, the control has no buddy window.

nUpper

Upper limit (range) of the up-down control.

nLower

Lower limit (range) of the up-down control.

nPos

Position of the control.

Return Value

If the function succeeds, the return value is the window handle of the up-down control.

If the function fails, the return value is NULL.


 CreateWindow

The CreateWindow function creates an overlapped, pop-up, or child window. It specifies the window class, window title, window style, and (optionally) the initial position and size of the window. The function also specifies the window's parent or owner, if any, and the window's menu.

HWND CreateWindow(

LPCTSTR  lpClassName,	// address of registered class name
LPCTSTR  lpWindowName,	// 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  hInstance,	// handle of application instance
LPVOID  lpParam	// address of window-creation data
);
Parameters

lpClassName

Points to a null-terminated string or is an integer atom. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.

If lpClassName is a string, it specifies the window class name. The class name can be any name registered with the RegisterClass function or any of the predefined control-class names. For a complete list, see the following Remarks section.

lpWindowName

Points to a null-terminated string that specifies the window name.

dwStyle

Specifies the style of the window being created. This parameter can be a combination of the window styles and control styles listed in the following Remarks section.

x

Specifies the initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial x-coordinate of the window's upper-left corner, in screen coordinates. For a child window, x is the x-coordinate of the upper-left corner of the window relative to the upper-left corner of the parent window's client area.

If this parameter is set to CW_USEDEFAULT, Windows selects the default position for the window's upper-left corner and ignores the y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified for a pop-up or child window, the x and y parameters are set to zero.

y

Specifies the initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-coordinate of the window's upper-left corner, in screen coordinates. For a child window, y is the initial y-coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window's client area. For a list box, y is the initial y-coordinate of the upper-left corner of the list box's client area relative to the upper-left corner of the parent window's client area.

If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to CW_USEDEFAULT, Windows ignores the y parameter.

nWidth

Specifies the width, in device units, of the window. For overlapped windows, nWidth is either the window's width, in screen coordinates, or CW_USEDEFAULT. If nWidth is CW_USEDEFAULT, Windows selects a default width and height for the window; the default width extends from the initial x-coordinate to the right edge of the screen, and the default height extends from the initial y-coordinate to the top of the icon area. CW_USEDEFAULT is valid only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child window, nWidth and nHeight are set to zero.

nHeight

Specifies the height, in device units, of the window. For overlapped windows, nHeight is the window's height, in screen coordinates. If nWidth is set to CW_USEDEFAULT, Windows ignores nHeight.

hWndParent

Identifies the parent or owner window of the window being created. A valid window handle must be supplied when a child window or an owned window is created. A child window is confined to the client area of its parent window. An owned window is an overlapped window that is destroyed when its owner window is destroyed or hidden when its owner is minimized; it is always displayed on top of its owner window. Although this parameter must specify a valid handle if the dwStyle parameter includes the WS_CHILD style, it is optional if dwStyle includes the WS_POPUP style.

hMenu

Identifies a menu, or specifies a child-window identifier depending on the window style. For an overlapped or pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box control to notify its parent about events. The application determines the child-window identifier; it must be unique for all child windows with the same parent window.

hInstance

Identifies the instance of the module to be associated with the window.

lpParam

Points to a value passed to the window through the CREATESTRUCT structure referenced by the lParam parameter of the WM_CREATE message. If an application calls CreateWindow to create a multiple document interface (MDI) client window, lpParam must point to a CLIENTCREATESTRUCT structure.

Return Value

If the function succeeds, the return value is the handle of the new window.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Before returning, CreateWindow sends a WM_CREATE message to the window procedure.

For overlapped, pop-up, and child windows, CreateWindow sends WM_CREATE, WM_GETMINMAXINFO, and WM_NCCREATE messages to the window. The lParam parameter of the WM_CREATE message contains a pointer to a CREATESTRUCT structure. If the WS_VISIBLE style is specified, CreateWindow sends the window all the messages required to activate and show the window.

If the window style specifies a title bar, the window title pointed to by lpWindowName is displayed in the title bar. When using CreateWindow to create controls, such as buttons, check boxes, and static controls, use lpWindowName to specify the text of the control.

The following predefined control classes can be specified in the lpClassName parameter:

Class	Meaning
BUTTON	Designates a small rectangular child window that represents a button the user can click to turn it on or off. Button controls can be used alone or in groups, and they can either be labeled or appear without text. Button controls typically change appearance when the user clicks them.
COMBOBOX	Designates a control consisting of a list box and a selection field similar to an edit control. When using this style, an application should either display the list box at all times or enable a drop-down list box.
	Depending on the style of the combo box, the user can or cannot edit the contents of the selection field. If the list box is visible, typing characters into the selection field highlights the first list box entry that matches the characters typed. Conversely, selecting an item in the list box displays the selected text in the selection field.
EDIT	Designates a rectangular child window into which the user can type text from the keyboard. The user selects the control and gives it the keyboard focus by clicking it or moving to it by pressing the TAB key. The user can type text when the edit control displays a flashing caret; use the mouse to move the cursor, select characters to be replaced, or position the cursor for inserting characters; or use the BACKSPACE key to delete characters.
	Edit controls use the variable-pitch system font and display characters from the ANSI character set. The WM_SETFONT message can also be sent to the edit control to change the default font.
	Edit controls expand tab characters into as many space characters as are required to move the caret to the next tab stop. Tab stops are assumed to be at every eighth character position.
LISTBOX	Designates a list of character strings. Specify this control whenever an application must present a list of names, such as filenames, from which the user can choose. The user can select a string by clicking it. A selected string is highlighted, and a notification message is passed to the parent window. Use a vertical or horizontal scroll bar with a list box to scroll lists that are too long for the control window. The list box automatically hides or shows the scroll bar, as needed.
MDICLIENT	Designates an MDI client window. This window receives messages that control the MDI application's child windows. The recommended style bits are WS_CLIPCHILDREN and WS_CHILD. Specify the WS_HSCROLL and WS_VSCROLL styles to create an MDI client window that allows the user to scroll MDI child windows into view.
SCROLLBAR	Designates a rectangle that contains a scroll box and has direction arrows at both ends. The scroll bar sends a notification message to its parent window whenever the user clicks the control. The parent window is responsible for updating the position of the scroll box, if necessary. Scroll bar controls have the same appearance and function as scroll bars used in ordinary windows. Unlike scroll bars, however, scroll bar controls can be positioned anywhere in a window for use whenever scrolling input is needed for a window.
	The scroll bar class also includes size box controls. A size box is a small rectangle the user can expand to change the size of the window.
STATIC	Designates a simple text field, box, or rectangle used to label, box, or separate other controls. Static controls take no input and provide no output.
The following window styles can be specified in the dwStyle parameter:

Style	Meaning
WS_BORDER	Creates a window that has a thin-line border.
WS_CAPTION	Creates a window that has a title bar (includes the WS_BORDER style).
WS_CHILD	Creates a child window. This style cannot be used with the WS_POPUP style.
WS_CHILDWINDOW	Same as the WS_CHILD style.
WS_CLIPCHILDREN	Excludes the area occupied by child windows when drawing occurs within the parent window. This style is used when creating the parent window.
WS_CLIPSIBLINGS	Clips child windows relative to each other; that is, when a particular child window receives a WM_PAINT message, the WS_CLIPSIBLINGS style clips all other overlapping child windows out of the region of the child window to be updated. If WS_CLIPSIBLINGS is not specified and child windows overlap, it is possible, when drawing within the client area of a child window, to draw within the client area of a neighboring child window.
WS_DISABLED	Creates a window that is initially disabled. A disabled window cannot receive input from the user.
WS_DLGFRAME	Creates a window that has a border of a style typically used with dialog boxes. A window with this style cannot have a title bar.
WS_GROUP	Specifies the first control of a group of controls. The 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_ICONIC	Creates a window that is initially minimized. Same as the WS_MINIMIZE style.
WS_MAXIMIZE	Creates a window that is initially maximized.
WS_MAXIMIZEBOX	Creates a window that has a Maximize button.
WS_MINIMIZE	Creates a window that is initially minimized. Same as the WS_ICONIC style.
WS_MINIMIZEBOX	Creates a window that has a Minimize button.
WS_OVERLAPPED	Creates an overlapped window. An overlapped window has a title bar and a border. Same as the WS_TILED style.
WS_OVERLAPPEDWINDOW	Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. Same as the WS_TILEDWINDOW style.
WS_POPUP	Creates a pop-up window. This style cannot be used with the WS_CHILD style.
WS_POPUPWINDOW	Creates a pop-up window with WS_BORDER, WS_POPUP, and WS_SYSMENU styles. The WS_CAPTION and WS_POPUPWINDOW styles must be combined to make the System menu visible.
WS_SIZEBOX	Creates a window that has a sizing border. Same as the WS_THICKFRAME style.
WS_SYSMENU	Creates a window that has a 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. Same as the WS_SIZEBOX style.
WS_TILED	Creates an overlapped window. An overlapped window has a title bar and a border. Same as the WS_OVERLAPPED style.
WS_TILEDWINDOW	Creates an overlapped window with the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles. Same as the WS_OVERLAPPEDWINDOW style.
WS_VISIBLE	Creates a window that is initially visible.
WS_VSCROLL	Creates a window that has a vertical scroll bar.
The following button styles (in the BUTTON class) can be specified in the dwStyle parameter:

Style	Meaning
BS_3STATE	Creates a button that is the same as a check box, except that the box can be grayed as well as checked. 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 the check state automatically toggles between checked and unchecked each time the user selects the check box.
BS_AUTORADIOBUTTON	Creates a button that is the same as a radio button, except that when the user selects it, Windows automatically sets the button's check state to checked and automatically sets the check state for all other buttons in the same group to unchecked.
BS_BITMAP	Specifies that the button displays a bitmap.
BS_BOTTOM	Places text at the bottom of the button rectangle.
BS_CENTER	Centers text horizontally in the button rectangle.
BS_CHECKBOX	Creates a small, empty check box with text. By default, the text is displayed to the right of the check box. To display the text to the left of the check box, combine this flag with the BS_LEFTTEXT style (or on Windows 95 only, with the equivalent BS_RIGHTBUTTON style).
BS_DEFPUSHBUTTON	Creates a push button that behaves like a BS_PUSHBUTTON style button, but also has a heavy black border. If the button is in a dialog box, the user can select the button by pressing the ENTER key, even when the button does not have the input focus. This style is useful for enabling the user to quickly select the most likely (default) option.
BS_GROUPBOX	Creates a rectangle in which other controls can be grouped. Any text associated with this style is displayed in the rectangle's upper-left corner.
BS_ICON	Specifies that the button displays an icon.
BS_LEFT	Left justifies the text in the button rectangle. However, if the button is a check box or radio button that does not have the BS_RIGHTBUTTON style, the text is left justified on the right side of the check box or radio button.
BS_LEFTTEXT	Places text on the left side of the radio button or check box when combined with a radio button or check box style. Same as the Windows 95 BS_RIGHTBUTTON style.
BS_MULTILINE	Wraps the button text to the second line if the text string is too long to fit on a single line in the button rectangle.
BS_NOTIFY	Sends the parent window notification messages other than BN_CLICKED or BN_DBLCLK, which a button sends regardless of whether it has this style.
BS_OWNERDRAW	Creates an owner-drawn button. The owner window receives a WM_MEASUREITEM message when the button is created and a WM_DRAWITEM message when a visual aspect of the button has changed. Do not combine the BS_OWNERDRAW style with any other button styles.
BS_PUSHBUTTON	Creates a push button that posts a WM_COMMAND message to the owner window when the user selects the button.
BS_PUSHLIKE	Makes a check box or radio button look and act like a push button.
BS_RADIOBUTTON	Creates a small circle with text. By default, the text is displayed to the right of the circle. To display the text to the left of the circle, combine this flag with the BS_LEFTTEXT style (or on Windows 95 only, with the equivalent BS_RIGHTBUTTON style). Use radio buttons for groups of related, but mutually exclusive choices.
BS_RIGHT	Right justifies text in the button rectangle. However, if the button is a check box or radio button that does not have the BS_RIGHTBUTTON style, the text is right justified on the right side of the check box or radio button.
BS_RIGHTBUTTON	Positions a radio button's circle or a check box's square on the right side of the button rectangle.
BS_TEXT	Specifies that the button displays text.
BS_TOP	Positions text at the top of the button rectangle.
BS_USERBUTTON	Obsolete. Applications should use BS_OWNERDRAW instead.
BS_VCENTER	Windows 95 only: Places text in the middle (vertically) of the button rectangle.
The following combo box styles (in the COMBOBOX class) can be specified in the dwStyle parameter:

Style	Meaning
CBS_AUTOHSCROLL	Automatically scrolls the text in an edit control to the right when the user types a character at the end of the line. If this style is not set, only text that fits within the rectangular boundary is allowed.
CBS_DISABLENOSCROLL	Shows a disabled vertical scroll bar in the list box when the box does not contain enough items to scroll. Without this style, the scroll bar is hidden when the list box does not contain enough items.
CBS_DROPDOWN	Similar to CBS_SIMPLE, except that the list box is not displayed unless the user selects an icon next to the edit control.
CBS_DROPDOWNLIST	Similar to CBS_DROPDOWN, except that the edit control is replaced by a static text item that displays the current selection in the list box.
CBS_HASSTRINGS	Specifies that an owner-drawn combo box contains items consisting of strings. The combo box maintains the memory and address for the strings, so the application can use the CB_GETLBTEXT message to retrieve the text for a particular item.
CBS_LOWERCASE	Converts to lowercase any uppercase characters entered into the edit control of a combo box.
CBS_NOINTEGRALHEIGHT	Specifies that the size of the combo box is exactly the size specified by the application when it created the combo box. Normally, Windows sizes a combo box so that it does not display partial items.
CBS_OEMCONVERT	Converts text entered in the combo box edit control. The text is converted from the Windows character set to the OEM character set and then back to the Windows set. This ensures proper character conversion when the application calls the CharToOem function to convert a Windows string in the combo box to OEM characters. This style is most useful for combo boxes that contain filenames and applies only to combo boxes created with the CBS_SIMPLE or CBS_DROPDOWN style.
CBS_OWNERDRAWFIXED	Specifies that the owner of the list box is responsible for drawing its contents and that the items in the list box are all the same height. The owner window receives a WM_MEASUREITEM message when the combo box is created and a WM_DRAWITEM message when a visual aspect of the combo box has changed.
CBS_OWNERDRAWVARIABLE	Specifies that the owner of the list box is responsible for drawing its contents and that the items in the list box are variable in height. The owner window receives a WM_MEASUREITEM message for each item in the combo box when you create the combo box; the owner window receives a WM_DRAWITEM message when a visual aspect of the combo box has changed.
CBS_SIMPLE	Displays the list box at all times. The current selection in the list box is displayed in the edit control.
CBS_SORT	Automatically sorts strings entered into the list box.
CBS_UPPERCASE	Converts to uppercase any lowercase characters entered into the edit control of a combo box.
The following edit control styles (in the EDIT class) can be specified in the dwStyle parameter:

Style	Meaning
ES_AUTOHSCROLL	Automatically scrolls text to the right by 10 characters when the user types a character at the end of the line. When the user presses the ENTER key, the control scrolls all text back to position zero.
ES_AUTOVSCROLL	Automatically scrolls text up one page when the user presses the ENTER key on the last line.
ES_CENTER	Centers text in a multiline edit control.
ES_LEFT	Left-aligns text.
ES_LOWERCASE	Converts all characters to lowercase as they are typed into the edit control.
ES_MULTILINE	Designates a multiline edit control. The default is single-line edit control.
	When the multiline edit control is in a dialog box, the default response to pressing the ENTER key is to activate the default button. To use the ENTER key as a carriage return, use the ES_WANTRETURN style.
	When the multiline edit control is not in a dialog box and the ES_AUTOVSCROLL style is specified, the edit control shows as many lines as possible and scrolls vertically when the user presses the ENTER key. If you do not specify ES_AUTOVSCROLL, the edit control shows as many lines as possible and beeps if the user presses the ENTER key when no more lines can be displayed.
	If you specify the ES_AUTOHSCROLL style, the multiline edit control automatically scrolls horizontally when the caret goes past the right edge of the control. To start a new line, the user must press the ENTER key. If you do not specify ES_AUTOHSCROLL, the control automatically wraps words to the beginning of the next line when necessary. A new line is also started if the user presses the ENTER key. The window size determines the position of the word wrap. If the window size changes, the word wrapping position changes and the text is redisplayed.
	Multiline edit controls can have scroll bars. An edit control with scroll bars processes its own scroll bar messages. Note that edit controls without scroll bars scroll as described in the previous paragraphs and process any scroll messages sent by the parent window.
ES_NOHIDESEL	Negates the default behavior for an edit control. The default behavior hides the selection when the control loses the input focus and inverts the selection when the control receives the input focus. If you specify ES_NOHIDESEL, the selected text is inverted, even if the control does not have the focus.
ES_NUMBER	Windows 95 only: Allows only digits to be entered into the edit control.
ES_OEMCONVERT	Converts text entered in the edit control. The text is converted from the Windows character set to the OEM character set and then back to the Windows set. This ensures proper character conversion when the application calls the CharToOem function to convert a Windows string in the edit control to OEM characters. This style is most useful for edit controls that contain filenames.
ES_PASSWORD	Displays an asterisk (*) for each character typed into the edit control. You can use the EM_SETPASSWORDCHAR message to change the character that is displayed.
ES_READONLY	Prevents the user from typing or editing text in the edit control.
ES_RIGHT	Right-aligns text in a multiline edit control.
ES_UPPERCASE	Converts all characters to uppercase as they are typed into the edit control.
ES_WANTRETURN	Specifies that a carriage return be inserted when the user presses the ENTER key while entering text into a multiline edit control in a dialog box. If you do not specify this style, pressing the ENTER key has the same effect as pressing the dialog box's default push button. This style has no effect on a single-line edit control.
The following list box control styles (in the LISTBOX class) can be specified in the dwStyle parameter:

Style	Meaning
LBS_DISABLENOSCROLL	Shows a disabled vertical scroll bar for the list box when the box does not contain enough items to scroll. If you do not specify this style, the scroll bar is hidden when the list box does not contain enough items.
LBS_EXTENDEDSEL	Allows multiple items to be selected by using the SHIFT key and the mouse or special key combinations.
LBS_HASSTRINGS	Specifies that a list box contains items consisting of strings. The list box maintains the memory and addresses for the strings so the application can use the LB_GETTEXT message to retrieve the text for a particular item. By default, all list boxes except owner-drawn list boxes have this style. You can create an owner-drawn list box either with or without this style.
LBS_MULTICOLUMN	Specifies a multicolumn list box that is scrolled horizontally. The LB_SETCOLUMNWIDTH message sets the width of the columns.
LBS_MULTIPLESEL	Turns string selection on or off each time the user clicks or double-clicks a string in the list box. The user can select any number of strings.
LBS_NODATA	Specifies a no-data list box. Specify this style when the count of items in the list box will exceed one thousand. A no-data list box must also have the LBS_OWNERDRAWFIXED style, but must not have the LBS_SORT or LBS_HASSTRINGS style.
	A no-data list box resembles an owner-drawn list box except that it contains no string or bitmap data for an item. Commands to add, insert, or delete an item always ignore any given item data; requests to find a string within the list box always fail. Windows sends the WM_DRAWITEM message to the owner window when an item must be drawn. The itemID member of the DRAWITEMSTRUCT structure passed with the WM_DRAWITEM message specifies the line number of the item to be drawn. A no-data list box does not send a WM_DELETEITEM message.
LBS_NOINTEGRALHEIGHT	Specifies that the size of the list box is exactly the size specified by the application when it created the list box. Normally, Windows sizes a list box so that the list box does not display partial items.
LBS_NOREDRAW	Specifies that the list box's appearance is not updated when changes are made. You can change this style at any time by sending a WM_SETREDRAW message.
LBS_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 parameters of CreateWindow.
SBS_LEFTALIGN	Aligns the left edge of the scroll bar with the left edge of the rectangle defined by the parameters of CreateWindow. The scroll bar has the default width for system scroll bars. Use this style with the SBS_VERT style.
SBS_RIGHTALIGN	Aligns the right edge of the scroll bar with the right edge of the rectangle defined by the parameters of CreateWindow. The scroll bar has the default width for system scroll bars. Use this style with the SBS_VERT style.
SBS_SIZEBOX	Designates a size box. If you specify neither the SBS_SIZEBOXBOTTOMRIGHTALIGN nor the SBS_SIZEBOXTOPLEFTALIGN style, the size box has the height, width, and position specified by the parameters of CreateWindow.
SBS_SIZEBOXBOTTOMRIGHTALIGN	Aligns the lower-right corner of the size box with the lower-right corner of the rectangle specified by the parameters of CreateWindow. The size box has the default size for system size boxes. Use this style with the SBS_SIZEBOX style.
SBS_SIZEBOXTOPLEFTALIGN	Aligns the upper-left corner of the size box with the upper-left corner of the rectangle specified by the parameters of CreateWindow. The size box has the default size for system size boxes. Use this style with the SBS_SIZEBOX style.
SBS_SIZEGRIP	Windows 95 only: Same as SBS_SIZEBOX, but with a raised edge.
SBS_TOPALIGN	Aligns the top edge of the scroll bar with the top edge of the rectangle defined by the parameters of CreateWindow. The scroll bar has the default height for system scroll bars. Use this style with the SBS_HORZ style.
SBS_VERT	Designates a vertical scroll bar. If you specify neither the SBS_RIGHTALIGN nor the SBS_LEFTALIGN style, the scroll bar has the height, width, and position specified by the parameters of CreateWindow.
The following static control styles (in the STATIC class) can be specified in the dwStyle parameter. A static control can have only one of these styles:

Style	Description
SS_BITMAP	Specifies a bitmap is to be displayed in the static control. The given text is the name of a bitmap (not a filename) defined elsewhere in the resource file. The style ignores the nWidth and nHeight parameters; the control automatically sizes itself to accommodate the bitmap.
SS_BLACKFRAME	Specifies a box with a frame drawn in the same color as the window frames. This color is black in the default Windows color scheme.
SS_BLACKRECT	Specifies a rectangle filled with the current window frame color. This color is black in the default Windows color scheme.
SS_CENTER	Specifies a simple rectangle and centers the 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_CENTERIMAGE	Specifies that the midpoint of a static control with the SS_BITMAP or SS_ICON style is to remain fixed when the control is resized. The four sides are adjusted to accommodate a new bitmap or icon. If a static control has the SS_BITMAP style and the bitmap is smaller than the control's client area, the client area is filled with the color of the pixel in the upper-left corner of the bitmap. If a static control has the SS_ICON style, the icon does not appear to paint the client area.
SS_GRAYFRAME	Specifies a box with a frame drawn with the same color as the screen background (desktop). This color is gray in the default Windows color scheme.
SS_GRAYRECT	Specifies a rectangle filled with the current screen background color. This color is gray in the default Windows color scheme.
SS_ICON	Specifies an icon displayed in the dialog box. The given text is the name of an icon (not a filename) defined elsewhere in the resource file. The style ignores the nWidth and nHeight parameters; the icon automatically sizes itself.
SS_LEFT	Specifies a simple rectangle and left-aligns the given text in the rectangle. The text is formatted before it is displayed. Words that extend past the end of a line are automatically wrapped to the beginning of the next left-aligned line.
SS_LEFTNOWORDWRAP	Specifies a simple rectangle and left-aligns the given text in the rectangle. Tabs are expanded but words are not wrapped. Text that extends past the end of a line is clipped.
SS_METAPICT	Specifies a metafile picture is to be displayed in the static control. The given text is the name of a metafile picture (not a filename) defined elsewhere in the resource file. A metafile static control has a fixed size; the metafile picture is scaled to fit the static control's client area.
SS_NOPREFIX	Prevents interpretation of any ampersand (&) characters in the control's text as accelerator prefix characters. These are displayed with the ampersand removed and the next character in the string underlined. This static control style may be included with any of the defined static controls.
	An application can combine SS_NOPREFIX with other styles by using the bitwise OR (|) operator. This can be useful when filenames or other strings that may contain an ampersand (&) must be displayed in a static control in a dialog box.
SS_NOTIFY	Sends the parent window STN_CLICKED and STN_DBLCLK notification messages when the user clicks or double clicks the control.
SS_RIGHT	Specifies a simple rectangle and right-aligns the given text in the rectangle. The text is formatted before it is displayed. Words that extend past the end of a line are automatically wrapped to the beginning of the next right-aligned line.
SS_RIGHTIMAGE	Specifies that the bottom-right corner of a static control with the SS_BITMAP or SS_ICON style is to remain fixed when the control is resized. Only the top and left sides are adjusted to accommodate a new bitmap or icon.
SS_SIMPLE	Specifies a simple rectangle and displays a single line of left-aligned text in the rectangle. The text line cannot be shortened or altered in any way. The control's parent window or dialog box must not process the WM_CTLCOLORSTATIC message.
SS_WHITEFRAME	Specifies a box with a frame drawn with the same color as the window backgrounds. This color is white in the default Windows color scheme.
SS_WHITERECT	Specifies a rectangle filled with the current window background color. This color is white in the default Windows color scheme.
The following dialog box styles can be specified in the dwStyle parameter:

Style	Meaning
DS_3DLOOK	Windows 95 only: Gives the dialog box a nonbold font and draws three-dimensional borders around control windows in the dialog box.
DS_ABSALIGN	Indicates that the coordinates of the dialog box are screen coordinates; otherwise, Windows assumes they are client coordinates.
DS_CENTER	Windows 95 only: Centers the dialog box in the working area; that is, the area not obscured by the tray.
DS_CENTERMOUSE	Windows 95 only: Centers the mouse cursor in the dialog box.
DS_CONTEXTHELP	Includes a question mark in the title bar of the dialog box. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a control in the dialog box, the control receives a WM_HELP message. The control should pass the message to the dialog procedure, which should call the WinHelp function using the HELP_WM_HELP command. The Help application displays a pop-up window that typically contains help for the control. Note that DS_CONTEXTHELP is just a placeholder. When the dialog box is created, the system checks for DS_CONTEXTHELP and, if it is there, adds WS_EX_CONTEXTHELP to the extended style of the dialog box.
DS_CONTROL	Windows 95 only: Creates a dialog box that works well as a child window of another dialog box, much like a page in a property sheet. This style allows the user to tab among the control windows of a child dialog box, use its accelerator keys, and so on.
DS_FIXEDSYS	Use SYSTEM_FIXED_FONT instead of SYSTEM_FONT.
DS_LOCALEDIT	Applies to 16-bit applications only. This style directs edit controls in the dialog box to allocate memory from the application's data segment. Otherwise, edit controls allocate storage from a global memory object.
DS_MODALFRAME	Creates a dialog box with a modal dialog-box frame that can be combined with a title bar and System menu by specifying the WS_CAPTION and WS_SYSMENU styles.
DS_NOFAILCREATE	Creates the dialog box even if errors occur — for example, if a child window cannot be created or if the system cannot create a special data segment for an edit control.
DS_NOIDLEMSG	Suppresses WM_ENTERIDLE messages that Windows would otherwise send to the owner of the dialog box while the dialog box is displayed.
DS_RECURSE	Dialog box style for control-like dialog boxes.
DS_SETFONT	Indicates that the dialog box template (the DLGTEMPLATE structure) contains two additional members specifying a font name and point size. The corresponding font is used to display text within the dialog box client area and within the dialog box controls. Windows passes the handle of the font to the dialog box and to each control by sending them the WM_SETFONT message.
DS_SETFOREGROUND	Does not apply to 16-bit versions of Microsoft Windows. This style brings the dialog box to the foreground. Internally, Windows calls the SetForegroundWindow function for the dialog box.
DS_SYSMODAL	Creates a system-modal dialog box.
See Also

CharToOem, CLIENTCREATESTRUCT, CreateDialog, CREATESTRUCT, CreateWindowEx, DialogBox, DLGTEMPLATE, DRAWITEMSTRUCT, GetDialogBaseUnits, GlobalAddAtom, LB_GETTEXT, LB_SETCOLUMNWIDTH, MessageBox, RegisterClass, SetForegroundWindow, WM_COMMAND, WM_CREATE, WM_DELETEITEM, WM_DRAWITEM, WM_ENTERIDLE, WM_GETMINMAXINFO, WM_MEASUREITEM, WM_NCCREATE, WM_PAINT, WM_SETFONT, WM_SETREDRAW, WM_VKEYTOITEM


 CreateWindowEx

The CreateWindowEx function creates an overlapped, pop-up, or child window with an extended style; otherwise, this function is identical to the CreateWindow function. For more information about creating a window and for full descriptions of the other parameters of CreateWindowEx, see CreateWindow.

HWND CreateWindowEx(

DWORD  dwExStyle,	// extended window style
LPCTSTR  lpClassName,	// address of registered class name
LPCTSTR  lpWindowName,	// 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  hInstance,	// handle of application instance
LPVOID  lpParam	// address of window-creation data
);
Parameters

dwExStyle

Specifies the extended style of the window. This parameter can be one of the following values:

Style	Meaning
WS_EX_ABSPOSITION	Specifies that a window has an absolute position. That is, the window does not move when the working area moves.
WS_EX_ACCEPTFILES	Specifies that a window created with this style accepts drag-drop files.
WS_EX_APPWINDOW	Windows 95 only: Forces a top-level window onto the application taskbar when the window is minimized.
WS_EX_CLIENTEDGE	Specifies that a window has a border with a sunken edge.
WS_EX_CONTEXTHELP	Includes a question mark in the title bar of the window. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a child window, the child receives a WM_HELP message. The child window should pass the message to the parent window procedure, which should call the WinHelp function using the HELP_WM_HELP command. The Help application displays a pop-up window that typically contains help for the child window.
WS_EX_CONTROLPARENT	Windows 95 only: Allows the user to navigate among the child windows of the window by using the TAB key.
WS_EX_DLGMODALFRAME	Creates a window that has a double border; the window can, optionally, be created with a title bar by specifying the WS_CAPTION style in the dwStyle parameter.
WS_EX_LEFT	Windows 95 only: Window has generic "left-aligned" properties. This is the default.
WS_EX_LEFTSCROLLBAR	Windows 95 only: Vertical scroll bar (if present) is to the left of the client area.
WS_EX_LTRREADING	Windows 95 only: The window text is displayed using Left to Right reading-order properties. This is the default.
WS_EX_MDICHILD	Creates an MDI child window.
WS_EX_NOPARENTNOTIFY	Specifies that a child window created with this style does not send the WM_PARENTNOTIFY message to its parent window when it is created or destroyed.
WS_EX_OVERLAPPEDWINDOW	Windows 95 only: Combines the WS_EX_CLIENTEDGE and WS_EX_WINDOWEDGE styles.
WS_EX_PALETTEWINDOW	Windows 95 only: Combines the WS_EX_WINDOWEDGE, WS_EX_SMCAPTION, and WS_EX_TOPMOST styles.
WS_EX_RIGHT	Windows 95 only: Window has generic "right-aligned" properties. This depends on the window class.
WS_EX_RIGHTSCROLLBAR	Windows 95 only: Vertical scroll bar (if present) is to the right of the client area. This is the default.
WS_EX_RTLREADING	Windows 95 only: The window text is displayed using Right to Left reading-order properties.
WS_EX_SMCAPTION	Creates a window that has a small title bar.
WS_EX_STATICEDGE	Windows 95 only: Creates a window with a three-dimensional border style intended to be used for items that do not accept user input.
WS_EX_TOOLWINDOW	Windows 95 only: Creates a tool window; that is, a window intended to be used as a floating toolbar. A tool window has a title bar that is shorter than a normal title bar, and the window title is drawn using a smaller font. A tool window does not appear in the task bar or in the window that appears when the user presses ALT+TAB.
WS_EX_TOPMOST	Specifies that a window created with this style should be placed above all non-topmost windows and should stay above them, even when the window is deactivated. To add or remove this style, use the SetWindowPos function.
WS_EX_TRANSPARENT	Specifies that a window created with this style is to be transparent. That is, any windows that are beneath the window are not obscured by the window. A window created with this style receives WM_PAINT messages only after all sibling windows beneath it have been updated.
WS_EX_WINDOWEDGE	Windows 95 only: Specifies that a window has a border with a raised edge.
Windows 95 only: Using the WS_EX_RIGHT style for static or edit controls has the same effect as using the SS_RIGHT or ES_RIGHT style, respectively. Using this style with button controls has the same effect as using BS_RIGHT and BS_RIGHTBUTTON styles.

lpClassName

Points to a null-terminated string or is an integer atom. If lpClassName is an atom, it must be a global atom created by a previous call to GlobalAddAtom. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.

If lpClassName is a string, it specifies the window class name. The class name can be any name registered with the RegisterClass function or any of the predefined control-class names.

lpWindowName

Points to a null-terminated string that specifies the window name.

dwStyle

Specifies the style of the window being created. For a list of the window styles that can be specified in dwStyle, see CreateWindow.

x

Specifies the initial horizontal position of the window. For an overlapped or pop-up window, the x parameter is the initial x-coordinate of the window's upper-left corner, in screen coordinates. For a child window, x is the x-coordinate of the upper-left corner of the window relative to the upper-left corner of the parent window's client area.

If x is set to CW_USEDEFAULT, Windows selects the default position for the window's upper-left corner and ignores the y parameter. CW_USEDEFAULT is valid only for overlapped windows; if it is specified for a pop-up or child window, the x and y parameters are set to zero.

y

Specifies the initial vertical position of the window. For an overlapped or pop-up window, the y parameter is the initial y-coordinate of the window's upper-left corner, in screen coordinates. For a child window, y is the initial y-coordinate of the upper-left corner of the child window relative to the upper-left corner of the parent window's client area. For a list box, y is the initial y-coordinate of the upper-left corner of the list box's client area relative to the upper-left corner of the parent window's client area.

If an overlapped window is created with the WS_VISIBLE style bit set and the x parameter is set to CW_USEDEFAULT, Windows ignores the y parameter.

nWidth

Specifies the width, in device units, of the window. For overlapped windows, nWidth is the window's width, in screen coordinates, or CW_USEDEFAULT. If nWidth is CW_USEDEFAULT, Windows selects a default width and height for the window; the default width extends from the initial x-coordinates to the right edge of the screen; the default height extends from the initial y-coordinate to the top of the icon area. CW_USEDEFAULT is valid only for overlapped windows; if CW_USEDEFAULT is specified for a pop-up or child window, the nWidth and nHeight parameter are set to zero.

nHeight

Specifies the height, in device units, of the window. For overlapped windows, nHeight is the window's height, in screen coordinates. If the nWidth parameter is set to CW_USEDEFAULT, Windows ignores nHeight.

hWndParent

Identifies the parent or owner window of the window being created. A valid window handle must be supplied when a child window or an owned window is created. A child window is confined to the client area of its parent window. An owned window is an overlapped window that is destroyed when its owner window is destroyed or hidden when its owner is minimized; it is always displayed on top of its owner window. Although this parameter must specify a valid handle if the dwStyle parameter includes the WS_CHILD style, it is optional if dwStyle includes the WS_POPUP style.

hMenu

Identifies a menu, or specifies a child-window identifier, depending on the window style. For an overlapped or pop-up window, hMenu identifies the menu to be used with the window; it can be NULL if the class menu is to be used. For a child window, hMenu specifies the child-window identifier, an integer value used by a dialog box control to notify its parent about events. The application determines the child-window identifier; it must be unique for all child windows with the same parent window.

hInstance

Identifies the instance of the module to be associated with the window.

lpParam

Points to a value passed to the window through the CREATESTRUCT structure referenced by the lParam parameter of the WM_CREATE message. If an application calls CreateWindow to create a multiple document interface client window, lpParam must point to a CLIENTCREATESTRUCT structure.

Return Value

If the function succeeds, the return value is the handle of the new window.

If the function fails, the return value is NULL.

Remarks

The CreateWindowEx function sends WM_NCCREATE, WM_NCCALCSIZE, and WM_CREATE messages to the window being created.

For information about the window control classes, window styles, and control styles used with this function, see the description of the CreateWindow function.

See Also

CLIENTCREATESTRUCT, CREATESTRUCT, CreateWindow, GlobalAddAtom, RegisterClass, SetWindowPos, WM_CREATE, WM_NCCALCSIZE, WM_NCCREATE, WM_PAINT, WM_PARENTNOTIFY


CreateWindowStation  (preliminaryWindows NT)
 CreateWindowStation  (preliminary−Windows NT)

The CreateWindowStation function creates a window station object. It returns a handle that can be used to access the window station. A window station is a secure object that contains a set of global atoms, a clipboard, and a set of desktop objects.

HWINSTA CreateWindowStation(

LPTSTR lpwinsta,	// name of the new window station
DWORD dwReserved,	// reserved; must be NULL
DWORD dwDesiredAccess	// specifies access of returned handle
LPSECURITY_ATTRIBUTES lpsa,	// specifies security attributes of the window station
);
Parameters

lpwinsta

Optionally points to a null-terminated string specifying the name of the window station to be created. Window station names are case-insensitive and cannot contain backslash characters (\). Only members of the Administrators group are allowed to specify a name. If lpwinsta is NULL, the system forms a window station name using the logon session identifier for the calling process. To get this name, call the GetUserObjectInformation function.

dwReserved

Reserved; must be NULL.

dwDesiredAccess

Specifies the type of access to the window station. This parameter can be one or more of the following values:

Value	Description
WINSTA_ACCESSCLIPBOARD	Required to use the clipboard.
WINSTA_ACCESSGLOBALATOMS	Required to manipulate global atoms.
WINSTA_CREATEDESKTOP	Required to create new desktop objects on the window station.
WINSTA_ENUMDESKTOPS	Required to enumerate existing desktop objects.
WINSTA_ENUMERATE	Required for the window station to be enumerated.
WINSTA_EXITWINDOWS	Required to successfully call the ExitWindows or ExitWindowsEx functions.
WINSTA_READATTRIBUTES	Required to read the attributes of a window station object.
WINSTA_READSCREEN	Required to access screen contents.
WINSTA_WRITEATTRIBUTES	Required to modify the attributes of a window station object.
lpsa

Points to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the window station.

If either lpsa or lpsa->lpSecurityDescriptor is NULL, the window station is assigned a security descriptor that grants GENERIC_ALL access to all users for the window station and any desktops created within the window station, and the resulting handle is not inheritable.

Return Value

If the function succeeds, the return value is the handle to the newly created window station.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

GetUserObjectInformation, OpenWindowStation


 DdeAbandonTransaction

The DdeAbandonTransaction function abandons the specified asynchronous transaction and releases all resources associated with the transaction.

BOOL DdeAbandonTransaction(

DWORD  idInst,	// instance identifier
HCONV  hConv,	// handle of conversation
DWORD  idTransaction	// transaction identifier
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hConv

Identifies the conversation in which the transaction was initiated. If this parameter is 0L, all transactions are abandoned (that is, the idTransaction parameter is ignored).

idTransaction

Specifies the identifier of the transaction to abandon. If this parameter is 0L, all active transactions in the specified conversation are abandoned.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR
DMLERR_UNFOUND_QUEUE_ID

Remarks

Only a dynamic data exchange (DDE) client application should call DdeAbandonTransaction. If the server application responds to the transaction after the client has called DdeAbandonTransaction, the system discards the transaction results. This function has no effect on synchronous transactions.

See Also

DdeClientTransaction, DdeInitialize, DdeQueryConvInfo


 DdeAccessData

The DdeAccessData function provides access to the data in the specified dynamic data exchange (DDE) object. An application must call the DdeUnaccessData function when it has finished accessing the data in the object.

LPBYTE DdeAccessData(

HDDEDATA  hData,	// handle of DDE object
LPDWORD  pcbDataSize	// address of variable that receives data length
);
Parameters

hData

Identifies the DDE object to access.

pcbDataSize

Points to a variable that receives the size, in bytes, of the DDE object identified by the hData parameter. If this parameter is NULL, no size information is returned.

Return Value

If the function succeeds, the return value is a pointer to the first byte of data in the DDE object.

If the function fails, the return value is NULL.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

Remarks

If the hData parameter has not been passed to a Dynamic Data Exchange Management Library (DDEML) function, an application can use the pointer returned by DdeAccessData for read-write access to the DDE object. If hData has already been passed to a DDEML function, the pointer should be used only for read access to the memory object.

See Also

DdeAddData, DdeCreateDataHandle, DdeFreeDataHandle, DdeUnaccessData


 DdeAddData

The DdeAddData function adds data to the specified dynamic data exchange (DDE) object. An application can add data starting at any offset from the beginning of the object. If new data overlaps data already in the object, the new data overwrites the old data in the bytes where the overlap occurs. The contents of locations in the object that have not been written to are undefined.

HDDEDATA DdeAddData(

HDDEDATA  hData,	// handle of DDE data object
LPBYTE  pSrc,	// address of source buffer
DWORD  cb,	// length of data
DWORD  cbOff	// offset within DDE data object
);
Parameters

hData

Identifies the DDE object that receives additional data.

pSrc

Points to a buffer containing the data to add to the DDE object.

cb

Specifies the length, in bytes, of the data to be added to the DDE object.

cbOff

Specifies an offset, in bytes, from the beginning of the DDE object. The additional data is copied to the object beginning at this offset.

Return Value

If the function succeeds, the return value is a new handle of the DDE object. The new handle is used in all references to the object.

If the function fails, the return value is zero.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_MEMORY_ERROR
DMLERR_NO_ERROR

Remarks

After a data handle has been used as a parameter in another Dynamic Data Exchange Management Library function or has been returned by a DDE callback function, the handle may be used only for read access to the DDE object identified by the handle.

If the amount of memory originally allocated is less than is needed to hold the added data, DdeAddData reallocates a global memory object of the appropriate size.

See Also

DdeAccessData, DdeCreateDataHandle, DdeUnaccessData


 DdeCallback

The DdeCallback function is an application-defined callback function that processes dynamic data exchange (DDE) transactions sent to the function in response to Dynamic Data Exchange Management Library (DDEML) calls by other applications.

HDDEDATA CALLBACK DdeCallback(

UINT  uType,	// transaction type
UINT  uFmt,	// clipboard data format
HCONV  hconv,	// handle 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
);
Parameters

uType

Specifies the type of the current transaction. This parameter consists of a combination of transaction class flags and transaction type flags. The following table describes each of the transaction classes and provides a list of the transaction types in each class. For information about a specific transaction type, see the individual description of that type.

Class	Meaning
XCLASS_BOOL	A DDE callback function should return TRUE or FALSE when it finishes processing a transaction that belongs to this class. The XCLASS_BOOL transaction class consists of the following types:
	XTYP_ADVSTART XTYP_CONNECT
XCLASS_DATA	A DDE callback function should return a DDE handle, the CBR_BLOCK return code, or NULL when it finishes processing a transaction that belongs to this class. The XCLASS_DATA transaction class consists of the following types:
	XTYP_ADVREQ XTYP_REQUEST XTYP_WILDCONNECT
XCLASS_FLAGS	A DDE callback function should return DDE_FACK, DDE_FBUSY, or DDE_FNOTPROCESSED when it finishes processing a transaction that belongs to this class. The XCLASS_FLAGS transaction class consists of the following types:
	XTYP_ADVDATA XTYP_EXECUTE XTYP_POKE
XCLASS_NOTIFICATION	The transaction types that belong to this class are for notification purposes only. The return value from the callback function is ignored. The XCLASS_NOTIFICATION transaction class consists of the following types: XTYP_ADVSTOP XTYP_CONNECT_CONFIRM XTYP_DISCONNECT XTYP_ERROR XTYP_MONITOR XTYP_REGISTER XTYP_XACT_COMPLETE XTYP_UNREGISTER
uFmt

Specifies the format in which data is sent or received.

hconv

Identifies the conversation associated with the current transaction.

hsz1

Identifies a string. The meaning of this parameter depends on the type of the current transaction. For the meaning of this parameter, see the description of the transaction type.

hsz2

Identifies a string. The meaning of this parameter depends on the type of the current transaction. For the meaning of this parameter, see the description of the transaction type.

hdata

Identifies DDE data. The meaning of this parameter depends on the type of the current transaction. For the meaning of this parameter, see the description of the transaction type.

dwData1

Specifies transaction-specific data. For the meaning of this parameter, see the description of the transaction type.

dwData2

Specifies transaction-specific data. For the meaning of this parameter, see the description of the transaction type.

Return Value

The return value depends on the transaction class. For more information about the return values, see descriptions of the individual transaction types.

Remarks

The callback function is called asynchronously for transactions that do not involve the creation or termination of conversations. An application that does not frequently accept incoming messages will have reduced DDE performance because the DDEML uses messages to initiate transactions.

An application must register the callback function by specifying a pointer to the function in a call to the DdeInitialize function.

DdeCallback is a placeholder for the application-defined or library-defined function name.

See Also

DdeEnableCallback, DdeInitialize


 DdeClientTransaction

The DdeClientTransaction function begins a data transaction between a client and a server. Only a dynamic data exchange (DDE) client application can call this function, and the application can use it only after establishing a conversation with the server.

HDDEDATA DdeClientTransaction(

LPBYTE  pData,	// 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  wFmt,	// clipboard data format
UINT  wType,	// transaction type
DWORD  dwTimeout,	// time-out duration
LPDWORD  pdwResult	// address of transaction result
);
Parameters

pData

Points to the beginning of the data the client must pass to the server.

Optionally, an application can specify the data handle (HDDEDATA) to pass to the server and in that case the cbData parameter should be set to 0xFFFFFFFF. This parameter is required only if the wType parameter is XTYP_EXECUTE or XTYP_POKE. Otherwise, this parameter should be NULL.

For the optional usage of this parameter, XTYP_POKE transactions where pData is a data handle, the handle must have been created by a previous call to the DdeCreateDataHandle function, employing the same data format specified in the wFmt parameter.

cbData

Specifies the length, in bytes, of the data pointed to by the pData parameter. A value of 0xFFFFFFFF indicates that pData is a data handle that identifies the data being sent.

hConv

Identifies the conversation in which the transaction is to take place.

hszItem

Identifies the data item for which data is being exchanged during the transaction. This handle must have been created by a previous call to the DdeCreateStringHandle function. This parameter is ignored (and should be set to 0L) if the wType parameter is XTYP_EXECUTE.

wFmt

Specifies the standard clipboard format in which the data item is being submitted or requested.

If the transaction specified by the wType parameter does not pass data or is XTYP_EXECUTE, this parameter should be zero.

If the transaction specified by the wType parameter references non-execute DDE data (XTYP_POKE, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_REQUEST), the wFmt value must be either a valid predefined (CF_) DDE format or a valid registered clipboard format.

wType

Specifies the transaction type. This parameter can be one of the following types:

Type	Meaning
XTYP_ADVSTART	Begins an advise loop. Any number of distinct advise loops can exist within a conversation. An application can alter the advise loop type by combining the XTYP_ADVSTART transaction type with one or more of the following flags:
Flag	Meaning
XTYPF_NODATA	Instructs the server to notify the client of any data changes without actually sending the data. This flag gives the client the option of ignoring the notification or requesting the changed data from the server.
XTYPF_ACKREQ	Instructs the server to wait until the client acknowledges that it received the previous data item before sending the next data item. This flag prevents a fast server from sending data faster than the client can process it.
XTYP_ADVSTOP	Ends an advise loop.
XTYP_EXECUTE	Begins an execute transaction.
XTYP_POKE	Begins a poke transaction.
XTYP_REQUEST	Begins a request transaction.
dwTimeout

Specifies the maximum length of time, in milliseconds, that the client will wait for a response from the server application in a synchronous transaction. This parameter should be TIMEOUT_ASYNC for asynchronous transactions.

pdwResult

Points to a variable that receives the result of the transaction. An application that does not check the result can use NULL for this value. For synchronous transactions, the low-order word of this variable contains any applicable DDE_ flags resulting from the transaction. This provides support for applications dependent on DDE_APPSTATUS bits. It is, however, recommended that applications no longer use these bits because they may not be supported in future versions of the Dynamic Data Exchange Management Library (DDEML). For asynchronous transactions, this variable is filled with a unique transaction identifier for use with the DdeAbandonTransaction function and the XTYP_XACT_COMPLETE transaction.

Return Value

If the function succeeds, the return value is a data handle that identifies the data for successful synchronous transactions in which the client expects data from the server. The return value is nonzero for successful asynchronous transactions and for synchronous transactions in which the client does not expect data. The return value is zero for all unsuccessful transactions.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_ADVACKTIMEOUT
DMLERR_BUSY
DMLERR_DATAACKTIMEOUT
DMLERR_DLL_NOT_INITIALIZED
DMLERR_EXECACKTIMEOUT
DMLERR_INVALIDPARAMETER
DMLERR_MEMORY_ERROR
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR
DMLERR_NOTPROCESSED
DMLERR_POKEACKTIMEOUT
DMLERR_POSTMSG_FAILED
DMLERR_REENTRANCY
DMLERR_SERVER_DIED
DMLERR_UNADVACKTIMEOUT

Remarks

When an application has finished using the data handle returned by DdeClientTransaction, the application should free the handle by calling the DdeFreeDataHandle function.

Transactions can be synchronous or asynchronous. During a synchronous transaction, DdeClientTransaction does not return until the transaction either completes successfully or fails. Synchronous transactions cause a client to enter a modal loop while waiting for various asynchronous events. Because of this, a client application can still respond to user input while waiting on a synchronous transaction, but the application cannot begin a second synchronous transaction because of the activity associated with the first. DdeClientTransaction fails if any instance of the same task has a synchronous transaction already in progress.

During an asynchronous transaction, DdeClientTransaction returns after the transaction has begun, passing a transaction identifier for reference. When the server's DDE callback function finishes processing an asynchronous transaction, the system sends an XTYP_XACT_COMPLETE transaction to the client. This transaction provides the client with the results of the asynchronous transaction that it initiated by calling DdeClientTransaction. A client application can choose to abandon an asynchronous transaction by calling the DdeAbandonTransaction function.

See Also

DdeAbandonTransaction, DdeAccessData, DdeConnect, DdeConnectList, DdeCreateDataHandle, DdeCreateStringHandle, DdeFreeDataHandle, XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_EXECUTE, XTYP_POKE, XTYP_REQUEST


 DdeCmpStringHandles

The DdeCmpStringHandles function compares the values of two string handles. The value of a string handle is not related to the case of the associated string.

int DdeCmpStringHandles(

HSZ  hsz1,	// handle of first string
HSZ  hsz2	// handle of second string
);
Parameters

hsz1

Identifies the first string.

hsz2

Identifies the second string.

Return Value

The return value can be one of the following values:

Value	Meaning
−1	The value of hsz1 is either 0 or less than the value of hsz2.
0	The values of hsz1 and hsz2 are equal (both can be 0).
1	The value of hsz2 is either 0 or less than the value of hsz1.
Remarks

An application that must do a case-sensitive comparison of two string handles should compare the string handles directly. An application should use DdeCmpStringHandles for all other comparisons to preserve the case-insensitive nature of dynamic data exchange (DDE).

DdeCmpStringHandles cannot be used to sort string handles alphabetically.

See Also

DdeAccessData, DdeCreateStringHandle, DdeFreeStringHandle


 DdeConnect

The DdeConnect function establishes a conversation with a server application that supports the specified service name and topic name pair. If more than one such server exists, the system selects only one.

HCONV DdeConnect(

DWORD  idInst,	// instance identifier
HSZ  hszService,	// handle of service name string
HSZ  hszTopic,	// handle of topic name string
PCONVCONTEXT  pCC	// address of structure with context data
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hszService

Identifies the string that specifies the service name of the server application with which a conversation is to be established. This handle must have been created by a previous call to the DdeCreateStringHandle function. If this parameter is 0L, a conversation is established with any available server.

hszTopic

Identifies the string that specifies the name of the topic on which a conversation is to be established. This handle must have been created by a previous call to DdeCreateStringHandle. If this parameter is 0L, a conversation on any topic supported by the selected server is established.

pCC

Points to the CONVCONTEXT structure that contains conversation context information. If this parameter is NULL, the server receives the default CONVCONTEXT structure during the XTYP_CONNECT or XTYP_WILDCONNECT transaction.

Return Value

If the function succeeds, the return value is the handle of the established conversation.

If the function fails, the return value is 0L.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR

Remarks

The client application cannot make assumptions regarding the server selected. If an instance-specific name is specified in the hszService parameter, a conversation is established with only the specified instance. Instance-specific service names are passed to an application's dynamic data exchange (DDE) callback function during the XTYP_REGISTER and XTYP_UNREGISTER transactions.

All members of the default CONVCONTEXT structure are set to zero except cb, which specifies the size of the structure, and iCodePage, which specifies CP_WINANSI (the default code page) or CP_WINUNICODE, depending on whether the ANSI or Unicode version of the DdeInitialize function was called by the client application.

See Also

CONVCONTEXT, DdeConnectList, DdeCreateStringHandle, DdeDisconnect, DdeDisconnectList, DdeInitialize, XTYP_REGISTER, XTYP_UNREGISTER


 DdeConnectList

The DdeConnectList function establishes a conversation with all server applications that support the specified service name and topic name pair. An application can also use this function to obtain a list of conversation handles by passing the function an existing conversation handle. The Dynamic Data Exchange Management Library removes the handles of any terminated conversations from the conversation list. The resulting conversation list contains the handles of all currently established conversations that support the specified service name and topic name.

HCONVLIST DdeConnectList(

DWORD  idInst,	// instance identifier
HSZ  hszService,	// handle 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
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hszService

Identifies the string that specifies the service name of the server application with which a conversation is to be established. If this parameter is 0L, the system attempts to establish conversations with all available servers that support the specified topic name.

hszTopic

Identifies the string that specifies the name of the topic on which a conversation is to be established. This handle must have been created by a previous call to the DdeCreateStringHandle function. If this parameter is 0L, the system will attempt to establish conversations on all topics supported by the selected server (or servers).

hConvList

Identifies the conversation list to be enumerated. This parameter should be 0L if a new conversation list is to be established.

pCC

Points to the CONVCONTEXT structure that contains conversation-context information. If this parameter is NULL, the server receives the default CONVCONTEXT structure during the XTYP_CONNECT or XTYP_WILDCONNECT transaction.

Return Value

If the function succeeds, the return value is the handle of a new conversation list.

If the function fails, the return value is 0L. The handle of the old conversation list is no longer valid.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALID_PARAMETER
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR
DMLERR_SYS_ERROR

Remarks

An application must free the conversation list handle returned by 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

CONVCONTEXT, DdeConnect, DdeCreateStringHandle, DdeDisconnect, DdeDisconnectList, DdeInitialize, DdeQueryNextServer


 DdeCreateDataHandle

The DdeCreateDataHandle function creates a dynamic data exchange (DDE) object and fills the object with data from the specified buffer. A DDE application uses this function during transactions that involve passing data to the partner application.

HDDEDATA DdeCreateDataHandle(

DWORD  idInst,	// instance identifier
LPBYTE  pSrc,	// address of source buffer
DWORD  cb,	// length of DDE object
DWORD  cbOff,	// offset from beginning of source buffer
HSZ  hszItem,	// handle of item name string
UINT  wFmt,	// clipboard data format
UINT  afCmd	// creation flags
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

pSrc

Points to a buffer that contains data to be copied to the DDE object. If this parameter is NULL, no data is copied to the object.

cb

Specifies the amount of memory, in bytes, to allocate for the DDE object. If this parameter is zero, the pSrc parameter is ignored.

cbOff

Specifies an offset, in bytes, from the beginning of the buffer pointed to by the pSrc parameter. The data beginning at this offset is copied from the buffer to the DDE object.

hszItem

Identifies the string that specifies the data item corresponding to the DDE object. This handle must have been created by a previous call to the DdeCreateStringHandle function. If the data handle is to be used in an XTYP_EXECUTE transaction, this parameter must be 0L.

wFmt

Specifies the standard clipboard format of the data.

afCmd

Specifies the creation flags. This parameter can be HDATA_APPOWNED, which specifies that the server application calling the DdeCreateDataHandle function owns the data handle this function creates. This flag enables the application to share the data handle with other Dynamic Data Exchange Management Library (DDEML) applications rather than creating a separate handle to pass to each application. If this flag is specified, the application must eventually free the shared memory object associated with the handle by using the DdeFreeDataHandle function. If this flag is not specified, the handle becomes invalid in the application that created the handle after the data handle is returned by the application's DDE callback function or is used as a parameter in another DDEML function.

Return Value

If the function succeeds, the return value is a data handle.

If the function fails, the return value is 0L.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_MEMORY_ERROR
DMLERR_NO_ERROR

Remarks

Any unfilled locations in the DDE object are undefined.

After a data handle has been used as a parameter in another DDEML function or has been returned by a DDE callback function, the handle may be used only for read access to the DDE object identified by the handle.

See Also

DdeAccessData, DdeCreateStringHandle, DdeFreeDataHandle, DdeGetData, DdeInitialize


 DdeCreateStringHandle

The DdeCreateStringHandle function creates a handle that identifies the string pointed to by the psz parameter. A dynamic data exchange (DDE) client or server application can pass the string handle as a parameter to other Dynamic Data Exchange Management Library (DDEML) functions.

HSZ DdeCreateStringHandle(

DWORD  idInst,	// instance identifier
LPTSTR  psz,	// address of null-terminated string
int  iCodePage	// code page identifier
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

psz

Points to a buffer that contains the null-terminated string for which a handle is to be created. This string may be of any length.

iCodePage

Specifies the code page used to render the string. This value should be either CP_WINANSI (the default code page) or CP_WINUNICODE, depending on whether the ANSI or Unicode version of DdeInitialize was called by the client application.

Return Value

If the function succeeds, the return value is a string handle.

If the function fails, the return value is 0L.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR
DMLERR_SYS_ERROR

Remarks

The value of a string handle is not related to the case of the string it identifies.

When an application either creates a string handle or receives one in the callback function and then uses the DdeKeepStringHandle function to keep it, the application must free that string handle when it is no longer needed.

An instance-specific string handle cannot be mapped from string handle to string and back to string handle. This is shown in the following example, in which the DdeQueryString function creates a string from a string handle and DdeCreateStringHandle creates a string handle from that string, but the two handles are not the same:

DWORD idInst;

DWORD cb;

HSZ hszInst, hszNew;

PSZ pszInst;

DdeQueryString(idInst, hszInst, pszInst, cb, CP_WINANSI);

hszNew = DdeCreateStringHandle(idInst, pszInst, CP_WINANSI);

// hszNew != hszInst !

See Also

DdeAccessData, DdeCmpStringHandles, DdeFreeStringHandle, DdeInitialize, DdeKeepStringHandle, DdeQueryString


 DdeDisconnect

The DdeDisconnect function terminates a conversation started by either the DdeConnect or DdeConnectList function and invalidates the specified conversation handle.

BOOL DdeDisconnect(

HCONV  hConv	// handle of conversation
);
Parameters

hConv

Identifies the active conversation to be terminated.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR

Remarks

Any incomplete transactions started before calling DdeDisconnect are immediately abandoned. The XTYP_DISCONNECT transaction is sent to the dynamic data exchange (DDE) callback function of the partner in the conversation. Generally, only client applications must terminate conversations.

See Also

DdeConnect, DdeConnectList, DdeDisconnectList, XTYP_DISCONNECT


 DdeDisconnectList

The DdeDisconnectList function destroys the specified conversation list and terminates all conversations associated with the list.

BOOL DdeDisconnectList(

HCONVLIST  hConvList	// handle of conversation list
);
Parameters

hConvList

Identifies the conversation list. This handle must have been created by a previous call to the DdeConnectList function.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

Remarks

An application can use the DdeDisconnect function to terminate individual conversations in the list.

See Also

DdeConnect, DdeConnectList, DdeDisconnect


 DdeEnableCallback

The DdeEnableCallback function enables or disables transactions for a specific conversation or for all conversations currently established by the calling application.

After disabling transactions for a conversation, the operating system places the transactions for that conversation in a transaction queue associated with the application. The application should reenable the conversation as soon as possible to avoid losing queued transactions.

BOOL DdeEnableCallback(

DWORD  idInst,	// instance identifier
HCONV  hConv,	// handle of conversation
UINT  wCmd	// enable or disable function code
);
Parameters

idInst

Specifies the application-instance identifier obtained by a previous call to the DdeInitialize function.

hConv

Identifies the conversation to enable or disable. If this parameter is NULL, the function affects all conversations.

wCmd

Specifies the function code. This parameter can be one of the following values:

Value	Meaning
EC_ENABLEALL	Enables all transactions for the specified conversation.
EC_ENABLEONE	Enables one transaction for the specified conversation.
EC_DISABLE	Disables all blockable transactions for the specified conversation. A server application can disable the following transactions: XTYP_ADVSTART XTYP_ADVSTOP XTYP_EXECUTE XTYP_POKE XTYP_REQUEST A client application can disable the following transactions: XTYP_ADVDATA XTYP_XACT_COMPLETE
EC_QUERYWAITING	Determines whether any transactions are in the queue for the specified conversation.
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

If the wCmd parameter is EC_QUERYWAITING, and the application transaction queue contains one or more unprocessed transactions that are not being processed, the return value is TRUE; otherwise, it is FALSE.

Errors

Use the DdeGetLastError function to retrieve the error value, which may be one of the following:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_NO_ERROR
DMLERR_INVALIDPARAMETER

Remarks

An application can disable transactions for a specific conversation by returning the CBR_BLOCK return code from its dynamic data exchange (DDE) callback function. When you reenable the conversation by using the DdeEnableCallback function, the operating system generates the same transaction that was in process when the conversation was disabled.

Using the EC_QUERYWAITING flag does not change the enable state of the conversation and does not cause transactions to be issued within the context of the call to DdeEnableCallback.

If DdeEnableCallback is called with EC_QUERYWAITING and the return value is TRUE, an application should try to quickly allow message processing, return from its callback, or enable callbacks. Such a result does not guarantee that subsequent callbacks will be made. Calling DdeEnableCallback with EC_QUERYWAITING lets an application with blocked callbacks determine whether there are any transactions pending on the blocked conversation. Of course, even if such a call returns false, an application should always process messages in a timely manner.

See Also

DdeConnect, DdeConnectList, DdeDisconnect, DdeInitialize


 DdeFreeDataHandle

The DdeFreeDataHandle function frees a dynamic data exchange (DDE) object and deletes the data handle associated with the object.

BOOL DdeFreeDataHandle(

HDDEDATA  hData	// handle of DDE object
);
Parameters

hData

Identifies the DDE object to be freed. This handle must have been created by a previous call to the DdeCreateDataHandle function or returned by the DdeClientTransaction function.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

Remarks

An application must call DdeFreeDataHandle under the following circumstances:

•	To free a DDE object that the application allocated by calling the DdeCreateDataHandle function if the object's data handle was never passed by the application to another Dynamic Data Exchange Management Library (DDEML) function

•	To free a DDE object that the application allocated by specifying the HDATA_APPOWNED flag in a call to DdeCreateDataHandle

•	To free a DDE object whose handle the application received from the DdeClientTransaction function

The system automatically frees an unowned object when its handle is returned by a DDE callback function or is used as a parameter in a DDEML function.

See Also

DdeAccessData, DdeCreateDataHandle, DdeClientTransaction


 DdeFreeStringHandle

The DdeFreeStringHandle function frees a string handle in the calling application.

BOOL DdeFreeStringHandle(

DWORD  idInst,	// instance identifier
HSZ  hsz	// handle of string
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hsz

Identifies the string handle to be freed. This handle must have been created by a previous call to the DdeCreateStringHandle function.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

An application can free string handles it creates with DdeCreateStringHandle but should not free those that the system passed to the application's dynamic data exchange (DDE) callback function or those returned in the CONVINFO structure by the DdeQueryConvInfo function.

See Also

CONVINFO, DdeCmpStringHandles, DdeCreateStringHandle, DdeInitialize, DdeKeepStringHandle, DdeQueryConvInfo, DdeQueryString


 DdeGetData

The DdeGetData function copies data from the specified dynamic data exchange (DDE) object to the specified local buffer.

DWORD DdeGetData(

HDDEDATA  hData,	// handle of DDE  object
LPBYTE  pDst,	// address of destination buffer
DWORD  cbMax,	// amount of data to copy
DWORD  cbOff	// offset to beginning of data
);
Parameters

hData

Identifies the DDE object that contains the data to copy.

pDst

Points to the buffer that receives the data. If this parameter is NULL, the DdeGetData function returns the amount of data, in bytes, that would be copied to the buffer.

cbMax

Specifies the maximum amount of data, in bytes, to copy to the buffer pointed to by the pDst parameter. Typically, this parameter specifies the length of the buffer pointed to by pDst.

cbOff

Specifies an offset within the DDE object. Data is copied from the object beginning at this offset.

Return Value

If the pDst parameter points to a buffer, the return value is the size, in bytes, of the memory object associated with the data handle or the size specified in the cbMax parameter, whichever is lower.

If the pDst parameter is NULL, the return value is the size, in bytes, of the memory object associated with the data handle.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

See Also

DdeAccessData, DdeCreateDataHandle, DdeFreeDataHandle


 DdeGetLastError

The DdeGetLastError function returns the most recent error value set by the failure of a Dynamic Data Exchange Management Library (DDEML) function and resets the error value to DMLERR_NO_ERROR.

UINT DdeGetLastError(

DWORD  idInst	// instance identifier
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

Return Value

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 flag to be set.
DMLERR_DATAACKTIMEOUT	A request for a synchronous data transaction has timed out.
DMLERR_DLL_NOT_INITIALIZED	A DDEML function was called without first calling the DdeInitialize function, or an invalid instance identifier was passed to a DDEML function.
DMLERR_DLL_USAGE	An application initialized as APPCLASS_MONITOR has attempted to perform a dynamic data exchange (DDE) transaction, or an application initialized as APPCMD_CLIENTONLY has attempted to perform server transactions.
DMLERR_EXECACKTIMEOUT	A request for a synchronous execute transaction has timed out.
DMLERR_INVALIDPARAMETER	A parameter failed to be validated by the DDEML. Some of the possible causes follow:
	The application used a data handle initialized with a different item name handle than was required by the transaction. The application used a data handle that was initialized with a different clipboard data format than was required by the transaction. The application used a client-side conversation handle with a server-side function or vice versa. The application used a freed data handle or string handle. More than one instance of the application used the same object.
DMLERR_LOW_MEMORY	A DDEML application has created a prolonged race condition (in which the server application outruns the client), causing large amounts of memory to be consumed.
DMLERR_MEMORY_ERROR	A memory allocation has failed.
DMLERR_NO_CONV_ESTABLISHED	A client's attempt to establish a conversation has failed.
DMLERR_NOTPROCESSED	A transaction has failed.
DMLERR_POKEACKTIMEOUT	A request for a synchronous poke transaction has timed out.
DMLERR_POSTMSG_FAILED	An internal call to the PostMessage function has failed.
DMLERR_REENTRANCY	An application instance with a synchronous transaction already in progress attempted to initiate another synchronous transaction, or the DdeEnableCallback function was called from within a DDEML callback function.
DMLERR_SERVER_DIED	A server-side transaction was attempted on a conversation terminated by the client, or the server terminated before completing a transaction.
DMLERR_SYS_ERROR	An internal error has occurred in the DDEML.
DMLERR_UNADVACKTIMEOUT	A request to end an advise transaction has timed out.
DMLERR_UNFOUND_QUEUE_ID	An invalid transaction identifier was passed to a DDEML function. Once the application has returned from an XTYP_XACT_COMPLETE callback, the transaction identifier for that callback function  is no longer valid.
See Also

DdeEnableCallback, DdeInitialize, PostMessage


 DdeImpersonateClient

The DdeImpersonateClient function impersonates a dynamic data exchange (DDE) client application in a DDE client conversation.

BOOL DdeImpersonateClient(

HCONV  hConv	// handle of DDE conversation
);
Parameters

hConv

Identifies the DDE client conversation to be impersonated.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Impersonation is the ability of a process to take on the security attributes of another process. When a client in a DDE conversation requests information from a DDE server, the server impersonates the client. When the server requests access to an object, the system verifies the access against the client's security attributes.

When the impersonation is complete, the server normally calls the RevertToSelf function.

See Also

ImpersonateNamedPipeClient, RevertToSelf


 DdeInitialize

The DdeInitialize function registers an application with the Dynamic Data Exchange Management Library (DDEML). An application must call this function before calling any other DDEML function.

UINT DdeInitialize(

LPDWORD  pidInst,	// address of instance identifier
PFNCALLBACK  pfnCallback,	// address of callback function
DWORD  afCmd,	// set of command and filter flags
DWORD  ulRes	// reserved
);
Parameters

pidInst

Points to the application instance identifier. At initialization, this parameter should point to 0. If the function succeeds, this parameter points to the instance identifier for the application. This value should be passed as the idInst parameter in all other DDEML functions that require it. If an application uses multiple instances of the DDEML dynamic-link library (DLL), the application should provide a different callback function for each instance.

If pidInst points to a nonzero value, reinitialization of the DDEML is implied. In this case, pidInst must point to a valid application-instance identifier.

pfnCallback

Points to the application-defined dynamic data exchange (DDE) callback function. This function processes DDE transactions sent by the system. For more information, see the DdeCallback callback function.

afCmd

Specifies a set of APPCMD_, CBF_, and MF_ flags. The APPCMD_ flags provide special instructions to DdeInitialize. The CBF_ flags specify filters that prevent specific types of transactions from reaching the callback function. The MF_ flags specify the types of DDE activity that a DDE monitoring application monitors. Using these flags enhances the performance of a DDE application by eliminating unnecessary calls to the callback function.

This parameter can be a combination of the following filter flags:

Flag	Meaning
APPCLASS_MONITOR	Makes it possible for the application to monitor DDE activity in the system. This flag is for use by DDE monitoring applications. The application specifies the types of DDE activity to monitor by combining one or more monitor flags with the APPCLASS_MONITOR flag. For details, see the following Remarks section.
APPCLASS_STANDARD	Registers the application as a standard (nonmonitoring) DDEML application.
APPCMD_CLIENTONLY	Prevents the application from becoming a server in a DDE conversation. The application can only be a client. This flag reduces consumption of resources by the DDEML. It includes the functionality of the CBF_FAIL_ALLSVRXACTIONS flag.
APPCMD_FILTERINITS	Prevents the DDEML from sending XTYP_CONNECT and XTYP_WILDCONNECT transactions to the application until the application has created its string handles and registered its service names or has turned off filtering by a subsequent call to the DdeNameService or DdeInitialize function. This flag is always in effect when an application calls DdeInitialize for the first time, regardless of whether the application specifies the flag. On subsequent calls to DdeInitialize, not specifying this flag turns off the application's service-name filters, but specifying it turns on the application's service name filters.
CBF_FAIL_ALLSVRXACTIONS	Prevents the callback function from receiving server transactions. The system returns DDE_FNOTPROCESSED to each client that sends a transaction to this application. This flag is equivalent to combining all CBF_FAIL_ flags.
CBF_FAIL_ADVISES	Prevents the callback function from receiving XTYP_ADVSTART and XTYP_ADVSTOP transactions. The system returns DDE_FNOTPROCESSED to each client that sends an XTYP_ADVSTART or XTYP_ADVSTOP transaction to the server.
CBF_FAIL_CONNECTIONS	Prevents the callback function from receiving XTYP_CONNECT and XTYP_WILDCONNECT transactions.
CBF_FAIL_EXECUTES	Prevents the callback function from receiving XTYP_EXECUTE transactions. The system returns DDE_FNOTPROCESSED to a client that sends an XTYP_EXECUTE transaction to the server.
CBF_FAIL_POKES	Prevents the callback function from receiving XTYP_POKE transactions. The system returns DDE_FNOTPROCESSED to a client that sends an XTYP_POKE transaction to the server.
CBF_FAIL_REQUESTS	Prevents the callback function from receiving XTYP_REQUEST transactions. The system returns DDE_FNOTPROCESSED to a client that sends an XTYP_REQUEST transaction to the server.
CBF_FAIL_SELFCONNECTIONS	Prevents the callback function from receiving XTYP_CONNECT transactions from the application's own instance. This flag prevents an application from establishing a DDE conversation with its own instance. An application should use this flag if it needs to communicate with other instances of itself but not with itself.
CBF_SKIP_ALLNOTIFICATIONS	Prevents the callback function from receiving any notifications. This flag is equivalent to combining all CBF_SKIP_ flags.
CBF_SKIP_CONNECT_CONFIRMS	Prevents the callback function from receiving XTYP_CONNECT_CONFIRM notifications.
CBF_SKIP_DISCONNECTS	Prevents the callback function from receiving XTYP_DISCONNECT notifications.
CBF_SKIP_REGISTRATIONS	Prevents the callback function from receiving XTYP_REGISTER notifications.
CBF_SKIP_UNREGISTRATIONS	Prevents the callback function from receiving XTYP_UNREGISTER notifications.
MF_CALLBACKS	Notifies the callback function whenever a transaction is sent to any DDE callback function in the system.
MF_CONV	Notifies the callback function whenever a conversation is established or terminated.
MF_ERRORS	Notifies the callback function whenever a DDE error occurs.
MF_HSZ_INFO	Notifies the callback function whenever a DDE application creates, frees, or increments the usage count of a string handle or whenever a string handle is freed as a result of a call to the DdeUninitialize function.
MF_LINKS	Notifies the callback function whenever an advise loop is started or ended.
MF_POSTMSGS	Notifies the callback function whenever the system or an application posts a DDE message.
MF_SENDMSGS	Notifies the callback function whenever the system or an application sends a DDE message.
ulRes

Reserved; must be set to zero.

Return Value

If the function succeeds, the return value is DMLERR_NO_ERROR.

If the function fails, the return value is one of the following values:

DMLERR_DLL_USAGE
DMLERR_INVALIDPARAMETER
DMLERR_SYS_ERROR

Remarks

An application that uses multiple instances of the DDEML must not pass DDEML objects between instances.

A DDE monitoring application should not attempt to perform DDE operations (establish conversations, issue transactions, and so on) within the context of the same application instance.

A synchronous transaction fails with a DMLERR_REENTRANCY error if any instance of the same task has a synchronous transaction already in progress.

The CBF_FAIL_ALLSVRACTIONS flag causes the DDEML to filter all server transactions and can be changed by a subsequent call to DdeInitialize. The APPCMD_CLIENTONLY flag prevents the DDEML from creating key resources for the server and cannot be changed by a subsequent call to DdeInitialize.

There is an ANSI version and a Unicode version of 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 XTYP_ADVSTART, XTYP_ADVSTOP, XTYP_CONNECT, XTYP_CONNECT_CONFIRM, XTYP_DISCONNECT, XTYP_EXECUTE, XTYP_POKE, XTYP_REGISTER, XTYP_REQUEST, XTYP_WILDCONNECT


 DdeKeepStringHandle

The DdeKeepStringHandle function increments the usage count associated with the specified handle. This function enables an application to save a string handle passed to the application's dynamic data exchange (DDE) callback function. Otherwise, a string handle passed to the callback function is deleted when the callback function returns. This function should also be used to keep a copy of a string handle referenced by the CONVINFO structure returned by the DdeQueryConvInfo function.

BOOL DdeKeepStringHandle(

DWORD  idInst,	// instance identifier
HSZ  hsz	// handle of string
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hsz

Identifies the string handle to be saved.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

CONVINFO, DdeCreateStringHandle, DdeFreeStringHandle, DdeInitialize, DdeQueryConvInfo, DdeQueryString


 DdeNameService

The DdeNameService function registers or unregisters the service names a dynamic data exchange (DDE) server supports. This function causes the system to send XTYP_REGISTER or XTYP_UNREGISTER transactions to other running Dynamic Data Exchange Management Library (DDEML) client applications.

A server application should call this function to register each service name that it supports and to unregister names it previously registered but no longer supports. A server should also call this function to unregister its service names just before terminating.

HDDEDATA DdeNameService(

DWORD  idInst,	// instance identifier
HSZ  hsz1,	// handle of service name string
HSZ  hsz2,	// reserved
UINT  afCmd	// service name flags
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hsz1

Identifies the string that specifies the service name the server is registering or unregistering. An application that is unregistering all of its service names should set this parameter to 0L.

hsz2

Reserved; should be set to 0L.

afCmd

Specifies the service name flags. This parameter can be one of the following flags:

Flag	Meaning
DNS_REGISTER	Registers the 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. The filter prevents a server from receiving XTYP_CONNECT transactions for service names it has not registered. This is the default setting for this filter.
	If a server application does not register any service names, the application cannot receive XTYP_WILDCONNECT transactions.
DNS_FILTEROFF	Turns off service name initiation filtering. If this flag is specified, the server receives an XTYP_CONNECT transaction whenever another DDE application calls the DdeConnect function, regardless of the service name.
Return Value

If the funcion succeeds, it returns a nonzero value. That value is not a true HDDEDATA value, merely a Boolean indicator of success. The function is typed HDDEDATA to allow for possible future expansion of the function and a more sophisticated return value.

If the function fails, the return value is 0L.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_DLL_USAGE
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

Remarks

The service name identified by the hsz1 parameter should be a base name (that is, the name should contain no instance-specific information). The system generates an instance-specific name and sends it along with the base name during the XTYP_REGISTER and XTYP_UNREGISTER transactions. The receiving applications can then connect to the specific application instance.

See Also

DdeConnect, DdeConnectList, DdeInitialize, XTYP_REGISTER, XTYP_UNREGISTER


 DdePostAdvise

The DdePostAdvise function causes the system to send an XTYP_ADVREQ transaction to the calling (server) application's dynamic data exchange (DDE) callback function for each client with an active advise loop on the specified topic and item. A server application should call this function whenever the data associated with the topic name or item name pair changes.

BOOL DdePostAdvise(

DWORD  idInst,	// instance identifier
HSZ  hszTopic,	// handle of topic name string
HSZ  hszItem	// handle of item name string
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hszTopic

Identifies a string that specifies the topic name. To send notifications for all topics with active advise loops, an application can set this parameter to 0L.

hszItem

Identifies a string that specifies the item name. To send notifications for all items with active advise loops, an application can set this parameter to 0L.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_DLL_USAGE
DMLERR_NO_ERROR

Remarks

A server that has nonenumerable topics or items should set the hszTopic and hszItem parameters to NULL so that the system generates transactions for all active advise loops. The server's DDE callback function returns NULL for any advise loops that must not be updated.

If a server calls DdePostAdvise with a topic, item, and format name set that includes the set currently being handled in an XTYP_ADVREQ callback, a stack overflow may result.

See Also

DdeInitialize, XTYP_ADVREQ


 DdeQueryConvInfo

The DdeQueryConvInfo function obtains information about a dynamic data exchange (DDE) transaction and about the conversation in which the transaction takes place.

UINT DdeQueryConvInfo(

HCONV  hConv,	// handle of conversation
DWORD  idTransaction,	// transaction identifier
PCONVINFO  pConvInfo	// address of structure with conversation data
);
Parameters

hConv

Identifies the conversation.

idTransaction

Specifies the transaction. For asynchronous transactions, this parameter should be a transaction identifier returned by the DdeClientTransaction function. For synchronous transactions, this parameter should be QID_SYNC.

pConvInfo

Points to the CONVINFO structure that receives information about the transaction and conversation. The cb member of the CONVINFO structure must specify the length of the buffer allocated for the structure.

Return Value

If the function succeeds, the return value is the number of bytes copied into the CONVINFO structure.

If the function fails, the return value is FALSE.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR
DMLERR_UNFOUND_QUEUE_ID

Remarks

An application should not free a string handle referenced by the CONVINFO structure. If an application must use one of these string handles, it should call the DdeKeepStringHandle function to create a copy of the handle.

If the idTransaction parameter is set to QID_SYNC, the hUser member of the CONVINFO structure is associated with the conversation and can be used to hold data associated with the conversation. If idTransaction is the identifier of an asynchronous transaction, the hUser member is associated only with the current transaction and is valid only for the duration of the transaction.

See Also

CONVINFO, DdeClientTransaction, DdeConnect, DdeConnectList, DdeKeepStringHandle, DdeQueryNextServer


 DdeQueryNextServer

The DdeQueryNextServer function obtains the next conversation handle in the specified conversation list.

HCONV DdeQueryNextServer(

HCONVLIST  hConvList,	// handle of conversation list
HCONV  hConvPrev	// previous conversation handle
);
Parameters

hConvList

Identifies the conversation list. This handle must have been created by a previous call to the DdeConnectList function.

hConvPrev

Identifies the conversation handle previously returned by this function. If this parameter is 0L, the function returns the first conversation handle in the list.

Return Value

If the list contains any more conversation handles, the return value is the next conversation handle in the list; otherwise, it is 0L.

See Also

DdeConnectList, DdeDisconnectList


 DdeQueryString

The DdeQueryString function copies text associated with a string handle into a buffer.

DWORD DdeQueryString(

DWORD  idInst,	// instance identifier
HSZ  hsz,	// handle of string
LPTSTR  psz,	// address of destination buffer
DWORD  cchMax,	// length of buffer
int  iCodePage	// code page identifier
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

hsz

Identifies the string to copy. This handle must have been created by a previous call to the DdeCreateStringHandle function.

psz

Points to a buffer that receives the string. To obtain the length of the string, this parameter should be set to NULL.

cchMax

Specifies the length, in characters, of the buffer pointed to by the psz parameter. If the string is longer than (cchMax − 1), it will be truncated. If the psz parameter is set to NULL, this parameter is ignored.

iCodePage

Specifies the code page used to render the string. This value should be either CP_WINANSI or CP_WINUNICODE.

Return Value

If the psz parameter specified a valid pointer, the return value is the length, in characters, of the returned text (not including the terminating null character). If the psz parameter specified a NULL pointer, the return value is the length of the text associated with the hsz parameter (not including the terminating null character). If an error occurs, the return value is 0L.

Remarks

The string returned in the buffer is always null-terminated. If the string is longer than (cchMax − 1), only the first (cchMax − 1) characters of the string are copied.

If the psz parameter is NULL, this function obtains the length, in bytes, of the string associated with the string handle. The length does not include the terminating null character.

See Also

DdeCmpStringHandles, DdeCreateStringHandle, DdeFreeStringHandle, DdeInitialize


 DdeReconnect

The DdeReconnect function allows a client Dynamic Data Exchange Management Library (DDEML) application to attempt to reestablish a conversation with a service that has terminated a conversation with the client. When the conversation is reestablished, the DDEML attempts to reestablish any preexisting advise loops.

HCONV DdeReconnect(

HCONV  hConv	// handle of conversation to reestablish
);
Parameters

hConv

Identifies the conversation to be reestablished. A client must have obtained the conversation handle by a previous call to the DdeConnect function or from an XTYP_DISCONNECT transaction.

Return Value

If the function succeeds, the return value is the handle of the reestablished conversation.

If the function fails, the return value is 0L.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_CONV_ESTABLISHED
DMLERR_NO_ERROR

See Also

DdeConnect, DdeDisconnect


 DdeSetQualityOfService

The DdeSetQualityOfService function specifies the quality of service a raw DDE application desires for future DDE conversations it initiates. The specified quality of service applies to any conversations started while those settings are in place. A DDE conversation's quality of service lasts for the duration of the conversation; calls to the DdeSetQualityOfService function during a given conversation do not affect that conversation's quality of service.

BOOL DdeSetQualityOfService(

HWND  hwndClient,	// handle of DDE client window that will start DDE conversations
CONST SECURITY_QUALITY_OF_SERVICE *  pqosNew,	// desired quality of service
PSECURITY_QUALITY_OF_SERVICE  pqosPrev	// prior quality of service
);
Parameters

hwndClient

Identifies the DDE client window that specifies the source of WM_DDE_INITIATE messages a client will send to start DDE conversations.

pqosNew

Points to a SECURITY_QUALITY_OF_SERVICE structure for the desired quality of service values.

pqosPrev

Points to a SECURITY_QUALITY_OF_SERVICE structure that the function will fill with the previous quality of service values associated with the window identified by hwndClient.

This parameter is optional. If an application has no interest in hwndClient's previous qos values, it should set pqosPrev to NULL.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The settings associated with a given hwndClient affect any conversation started subsequent to calling the DdeSetQualityOfService function. The settings remain in effect for the duration of any DDE conversation started under them. Once an application starts a DDE conversation using a particular quality of service value, it must terminate the conversation and restart the conversation in order to have a different value take effect. If a quality of service has not been specified for a given hwndClient prior to sending a WM_DDE_INITIATE with the wParam set to hwndClient, the system uses the following default quality of service values:

{

Length = sizeof(SECURITY_QUALITY_OF_SERVICE);

ImpersonationLevel = SecurityImpersonation;

ContextTrackingMode = SECURITY_STATIC_TRACKING;

EffectiveOnly = TRUE;

}

See Also

DdeConnect, DdeConnectList, DdeImpersonateClient, ImpersonateDdeClientWindow, SECURITY_QUALITY_OF_SERVICE, WM_DDE_INITIATE


 DdeSetUserHandle

The DdeSetUserHandle function associates an application-defined 32-bit value with a conversation handle or a transaction identifier. This is useful for simplifying the processing of asynchronous transactions. An application can use the DdeQueryConvInfo function to retrieve this value.

BOOL DdeSetUserHandle(

HCONV  hConv,	// handle of conversation
DWORD  id,	// transaction identifier
DWORD  hUser	// handle of application-defined value
);
Parameters

hConv

Identifies the conversation.

id

Specifies the transaction identifier to associate with the value specified by the hUser parameter. An application should set this parameter to QID_SYNC to associate hUser with the conversation identified by the hConv parameter.

hUser

Identifies the value to associate with the conversation handle.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR
DMLERR_UNFOUND_QUEUE_ID

See Also

DdeQueryConvInfo


 DdeUnaccessData

The DdeUnaccessData function unaccesses a dynamic data exchange (DDE) object. An application must call this function after it has finished accessing the object.

BOOL DdeUnaccessData(

HDDEDATA  hData	// handle of DDE object
);
Parameters

hData

Identifies the DDE object.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Errors

The DdeGetLastError function can be used to get the error value, which may be one of the following values:

DMLERR_DLL_NOT_INITIALIZED
DMLERR_INVALIDPARAMETER
DMLERR_NO_ERROR

See Also

DdeAccessData, DdeAddData, DdeCreateDataHandle, DdeFreeDataHandle


 DdeUninitialize

The DdeUninitialize function frees all Dynamic Data Exchange Management Library (DDEML) resources associated with the calling application.

BOOL DdeUninitialize(

DWORD  idInst	// instance identifier
);
Parameters

idInst

Specifies the application instance identifier obtained by a previous call to the DdeInitialize function.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

DdeUninitialize terminates any conversations currently open for the application.

See Also

DdeDisconnect, DdeDisconnectList, DdeInitialize


 DebugActiveProcess

The DebugActiveProcess function allows a debugger to attach to an active process and then debug it.

BOOL DebugActiveProcess(

DWORD  dwProcessId	// process to be debugged
);
Parameters

dwProcessId

Specifies the identifier for the process to be debugged. The debugger gets debugging access to the process as if it created the process with the DEBUG_ONLY_THIS_PROCESS flag.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The debugger must have appropriate access to the target process; it must be able to open the process for PROCESS_ALL_ACCESS access. In the Win32 application programming interface (API) for Windows 95, this is always true if the process identifier is valid. However, In the Win32 API for Windows NT, DebugActiveProcess can fail if the target process was created with a security descriptor that denies the debugger appropriate access.

After the system checks the process identifier and determines that a valid debugging attachment is being made, the function returns TRUE. The debugger is then expected to wait for debugging events by using the WaitForDebugEvent function. The system suspends all threads in the process and sends the debugger events representing the current state of the process.

The system sends the debugger a single CREATE_PROCESS_DEBUG_EVENT debugging event representing the process specified by the dwProcessId parameter. The lpStartAddress member of the CREATE_PROCESS_DEBUG_INFO structure is NULL.

For each thread currently part of the process, the system sends a CREATE_THREAD_DEBUG_EVENT debugging event. The lpStartAddress member of the CREATE_THREAD_DEBUG_INFO structure is NULL.

For each dynamic-link library (DLL) currently loaded into the address space of the target process, the system sends a LOAD_DLL_DEBUG_EVENT debugging event. The system arranges for the first thread in the process to execute a breakpoint instruction after it resumes. Continuing this thread causes it to return to whatever it was doing before the debugger was attached.

After all of this has been done, the system resumes all threads in the process. When the first thread in the process resumes, it executes a breakpoint instruction that causes an EXCEPTION_DEBUG_EVENT debugging event to be sent to the debugger. All future debugging events are sent to the debugger by using the normal mechanism and rules.

See Also

CreateProcess, CREATE_PROCESS_DEBUG_INFO, CREATE_THREAD_DEBUG_INFO, WaitForDebugEvent


 DebugBreak

The DebugBreak function causes a breakpoint exception to occur in the current process so that the calling thread can signal the debugger and force it to take some action. If the process is not being debugged, the search logic of a standard exception handler is used. In most cases, this causes the calling process to terminate because of an unhandled breakpoint exception.

VOID DebugBreak(VOID)

Parameters

This function has no parameters.

Return Value

This function does not return a value.

See Also

DebugActiveProcess


 DebugProc

The DebugProc hook procedure is an application-defined or library-defined callback function that Windows calls before calling the hook procedures associated with any other type of hook. The system passes information about the hook to be called to the DebugProc hook procedure, which examines the information and determines whether to allow the hook to be called.

LRESULT CALLBACK DebugProc(

int  nCode,	// hook code
WPARAM  wParam,	// type of hook about to be called
LPARAM  lParam	// address of structure with debugging information
);
Parameters

nCode

Specifies whether the hook procedure must process the message. If nCode is HC_ACTION, the hook procedure must process the message. If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies the type of hook about to be called. This parameter can be one of the following values:

Value	Description
WH_CALLWNDPROC	Installs a hook procedure that monitors messages sent to a window procedure. For more information, see the description of the CallWndProc hook procedure.
WH_CALLWNDPROCRET	Windows 95 only: Installs a hook procedure that monitors messages that have just been processed by a window procedure. For more information, see the description of the CallWndRetProc hook procedure.
WH_CBT	Installs a hook procedure that receives notifications useful to a computer-based training (CBT) application. For more information, see the description of the CBTProc hook procedure.
WH_DEBUG	Installs a hook procedure useful for debugging other hook procedures. For more information, see the description of the DebugProc hook procedure.
WH_GETMESSAGE	Installs a hook procedure that monitors messages posted to a message queue. For more information, see the description of the GetMsgProc hook procedure.
WH_JOURNALPLAYBACK	Installs a hook procedure that posts messages previously recorded by a WH_JOURNALRECORD hook procedure. For more information, see the description of the JournalPlaybackProc hook procedure.
WH_JOURNALRECORD	Installs a hook procedure that records input messages posted to the system message queue. This hook is useful for recording macros. For more information, see the description of the JournalRecordProc hook procedure.
WH_KEYBOARD	Installs a hook procedure that monitors keystroke messages. For more information, see the description of the KeyboardProc hook procedure.
WH_MOUSE	Installs a hook procedure that monitors mouse messages. For more information, see the description of the MouseProc hook procedure.
WH_MSGFILTER	Installs a hook procedure that monitors messages generated as a result of an input event in a dialog box, message box, menu, or scroll bar. The hook procedure monitors these messages only for the application that installed the hook procedure. For more information, see the description of the MessageProc hook procedure.
WH_SHELL	Installs a hook procedure that receives notifications useful to a shell application. For more information, see the description of the ShellProc hook procedure.
WH_SYSMSGFILTER	Installs a hook procedure that monitors messages generated as a result of an input event in a dialog box, message box, menu, or scroll bar. The hook procedure monitors these messages for all applications in the system. For more information, see the description of the SysMsgProc hook procedure.
lParam

Points to a DEBUGHOOKINFO structure that contains the parameters to be passed to the destination hook procedure.

Return Value

To prevent the system from calling the hook, the return value must be a nonzero value. Otherwise, the hook procedure must pass the hook information to the CallNextHookEx function.

Remarks

An application installs this hook procedure by specifying the WH_DEBUG hook type and the 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, CallWndProc, CBTProc, DEBUGHOOKINFO, GetMsgProc, JournalPlaybackProc, JournalRecordProc, KeyboardProc, MessageProc, MouseProc, SetWindowsHookEx, ShellProc, SysMsgProc


 DefDlgProc

The DefDlgProc function carries out default message processing for a window procedure belonging to an application-defined dialog box class.

LRESULT DefDlgProc(

HWND  hDlg,	// handle of dialog box
UINT  Msg,	// message
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hDlg

Identifies the dialog box.

Msg

Specifies the message number.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

The return value specifies the result of the message processing and depends on the message sent.

Remarks

The DefDlgProc function is the window procedure for the predefined class of dialog box. This procedure provides internal processing for the dialog box by forwarding messages to the dialog box procedure and carrying out default processing for any messages that the dialog box procedure returns as FALSE. Applications that create custom window procedures for their custom dialog boxes often use 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

The DeferWindowPos function updates the specified multiple-window − position structure for the specified 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.

HDWP DeferWindowPos(

HDWP  hWinPosInfo,	// 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  uFlags	// window-positioning flags
);
Parameters

hWinPosInfo

Identifies a multiple-window − position structure that contains size and position information for one or more windows. This structure is returned by BeginDeferWindowPos or by the most recent call to DeferWindowPos.

hWnd

Identifies the window for which update information is stored in the structure.

hWndInsertAfter

Identifies the window that precedes the positioned window in the Z order. This parameter must be a window handle or one of the following values:

Value	Meaning
HWND_BOTTOM	Places the window at the bottom of the Z order. If the hWnd parameter identifies a topmost window, the window loses its topmost status and is placed at the bottom of all other windows.
HWND_NOTOPMOST	Places the window above all non-topmost windows (that is, behind all topmost windows). This flag has no effect if the window is already a non-topmost window.
HWND_TOP	Places the window at the top of the Z order.
HWND_TOPMOST	Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated.
This parameter is ignored if the SWP_NOZORDER flag is set in the uFlags parameter.

x

Specifies the x-coordinate of the window's upper-left corner.

y

Specifies the y-coordinate of the window's upper-left corner.

cx

Specifies the window's new width, in pixels.

cy

Specifies the window's new height, in pixels.

uFlags

Specifies a combination of the following values that affect the size and position of the window:

Value	Meaning
SWP_DRAWFRAME	Draws a frame (defined in the window's class description) around the window.
SWP_HIDEWINDOW	Hides the window.
SWP_NOACTIVATE	Does not activate the window.
SWP_NOMOVE	Retains the current position (ignores the x and y parameters).
SWP_NOOWNERZORDER	Does not change the owner window's position in the Z order.
SWP_NOREDRAW	Does not redraw changes. If this flag is set, no repainting 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_NOREPOSITION	Currently the same as the SWP_NOOWNERZORDER flag.
SWP_NOSENDCHANGING	Windows 95 only: Prevents the window from receiving the WM_WINDOWPOSCHANGING message.
SWP_NOSIZE	Retains the current size (ignores the cx and cy parameters).
SWP_NOZORDER	Retains the current Z order (ignores the hWndInsertAfter parameter).
SWP_SHOWWINDOW	Displays the window.
Return Value

The return value identifies the updated multiple-window − position structure. The handle returned by this function may differ from the handle passed to the function. The new handle that this function returns should be passed during the next call to the DeferWindowPos or EndDeferWindowPos function.

If insufficient system resources are available for the function to succeed, the return value is NULL.

Remarks

If a call to DeferWindowPos fails, the application should abandon the window-positioning operation and not call EndDeferWindowPos.

If SWP_NOZORDER is not specified, Windows places the window identified by the hWnd parameter in the position following the window identified by the hWndInsertAfter parameter. If hWndInsertAfter is NULL or HWND_TOP, Windows places the hWnd window at the top of the Z order. If hWndInsertAfter is set to HWND_BOTTOM, Windows places the hWnd window at the bottom of the Z order.

All coordinates for child windows are relative to the upper-left corner of the parent window's client area.

A window can be made a topmost window either by setting hWndInsertAfter to the HWND_TOPMOST flag and ensuring that the SWP_NOZORDER flag is not set, or by setting the window's position in the Z order so that it is above any existing topmost windows. When a non-topmost window is made topmost, its owned windows are also made topmost. Its owners, however, are not changed.

If neither the SWP_NOACTIVATE nor SWP_NOZORDER flag is specified (that is, when the application requests that a window be simultaneously activated and its position in the Z order changed), the value specified in hWndInsertAfter is used only in the following circumstances:

•	Neither the HWND_TOPMOST nor HWND_NOTOPMOST flag is specified in hWndInsertAfter.

•	The window identified by hWnd is not the active window.

An application cannot activate an inactive window without also bringing it to the top of the Z order. An application can change an activated window's position in the Z order without restrictions, or it can activate a window and then move it to the top of the topmost or non-topmost windows.

A topmost window is no longer topmost if it is repositioned to the bottom (HWND_BOTTOM) of the Z order or after any non-topmost window. When a topmost window is made non-topmost, its owners and its owned windows are also made non-topmost windows.

A non-topmost window may own a topmost window, but not vice versa. Any window (for example, a dialog box) owned by a topmost window is itself made a topmost window to ensure that all owned windows stay above their owner.

See Also

BeginDeferWindowPos, EndDeferWindowPos, ShowWindow


 DefFrameProc

The DefFrameProc function provides default processing for any window messages that the window procedure of a multiple document interface (MDI) frame window does not process. All window messages that are not explicitly processed by the window procedure must be passed to the DefFrameProc function, not the DefWindowProc function.

LRESULT DefFrameProc(

HWND  hWnd,	// handle of MDI frame window
HWND  hWndMDIClient,	// handle of MDI client window
UINT  uMsg,	// message
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hWnd

Identifies the MDI frame window.

hWndMDIClient

Identifies the MDI client window.

uMsg

Specifies the message to be processed.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

The return value specifies the result of the message processing and depends on the message. If the hWndMDIClient parameter is NULL, the return value is the same as for the DefWindowProc function.

Remarks

When an application's window procedure does not handle a message, it typically passes the message to the DefWindowProc function to process the message. MDI applications use the DefFrameProc and DefMDIChildProc functions instead of DefWindowProc to provide default message processing. All messages that an application would usually pass to DefWindowProc (such as nonclient messages and the WM_SETTEXT message) should be passed to DefFrameProc instead. The DefFrameProc function also handles the following messages:

Message	Response
WM_COMMAND	Activates the MDI child window that the user chooses. This message is sent when the user chooses an MDI child window from the Window menu of the MDI frame window. The window identifier accompanying this message identifies the MDI child window to be activated.
WM_MENUCHAR	Opens the 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, WM_SETTEXT


 DefHookProc

The DefHookProc function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the CallNextHookEx function.


 DefineDosDevice

The DefineDosDevice function lets an application define, redefine, or delete MS-DOS device names.

MS-DOS device names are stored as symbolic links in the object name space in 32-bit versions of Windows. The code that converts an MS-DOS path into a corresponding path in 32-bit versions of Windows uses these symbolic links to map MS-DOS devices and drive letters. The DefineDosDevice function provides a mechanism whereby a Win32-based application can modify the symbolic links used to implement the MS-DOS device name space.

BOOL DefineDosDevice(

DWORD  dwFlags,	// flags specifying aspects of device definition
LPCTSTR  lpDeviceName,	// address of MS-DOS device name string
LPCTSTR  lpTargetPath	// address of MS-DOS or path string for 32-bit Windows
);
Parameters

dwFlags

Specifies several controllable aspects of the DefineDosDevice function. One or more of the following values can be used:

Value	Meaning
DDD_RAW_TARGET_PATH	If this value is specified, the function does not convert the lpTargetPath string from an MS-DOS path to a path for a 32-bit version of Windows, but takes it as is.
DDD_REMOVE_DEFINITION	If this value is specified, the function removes the specified definition for the specified device. To determine which definition to remove, the function walks the list of mappings for the device, looking for a match of lpTargetPath against a prefix of each mapping associated with this device. The first mapping that matches is the one removed, and then the function returns. If lpTargetPath is NULL or a pointer to a NULL string, the function will remove the first mapping associated with the device and pop the most recent one pushed. If there is nothing left to pop, the device name will be removed. If this value is NOT specified, the string pointed to by the lpTargetPath parameter will become the new mapping for this device.
DDD_EXACT_MATCH_ON_REMOVE	If this value is specified along with DDD_REMOVE_DEFINITION, the function will use an exact match to determine which mapping to remove. Use this value to insure that you do not delete something that you did not define.
lpDeviceName

Points to an MS-DOS device name string specifying the device the function is defining, redefining, or deleting. The device name string must not have a trailing colon, unless a drive letter (C or D, for example) is being defined, redefined, or deleted.

lpTargetPath

Points to a path string that will implement this device. Points to an MS-DOS path string unless the DDD_RAW_TARGET_PATH flag is specified, in which case this parameter points to a path string for a 32-bit version of Windows.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

As stated in this function's introductory summary, the DefineDosDevice function provides a means whereby a Win32-based application can create and modify the symbolic links used to implement the MS-DOS device namespace. To retrieve the current mapping for a particular MS-DOS device name or to obtain a list of all MS-DOS devices known to the system, use the QueryDosDevice function.

MS-DOS Device names are global. Once defined, an MS-DOS device name remains visible to all processes until either it is explicitly removed or the system reboots.

Note that drive letters and device names defined at system boot time are protected from redefinition and deletion unless a user is running in administrative mode (ADMIN).

See Also

QueryDosDevice


DefineHandleTable

The DefineHandleTable function is obsolete. It is provided as a macro to simplify porting of 16-bit Windows-based applications. It expands to TRUE after evaluating its argument. It has no other effect.


DefMDIChildProc

The DefMDIChildProc function provides default processing for any window message that the window procedure of a multiple document interface (MDI) child window does not process. A window message not processed by the window procedure must be passed to the DefMDIChildProc function, not to the DefWindowProc function.

LRESULT DefMDIChildProc(

HWND  hWnd,	// handle of MDI child window
UINT  uMsg,	// message
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hWnd

Identifies the MDI child window.

uMsg

Specifies the message to be processed.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

The return value specifies the result of the message processing and depends on the message.

Remarks

The DefMDIChildProc function assumes that the parent window of the MDI child window identified by the hWnd parameter was created with the MDICLIENT class.

When an application's window procedure does not handle a message, it typically passes the message to the DefWindowProc function to process the message. MDI applications use the DefFrameProc and DefMDIChildProc functions instead of DefWindowProc to provide default message processing. All messages that an application would usually pass to DefWindowProc (such as nonclient messages and the WM_SETTEXT message) should be passed to DefMDIChildProc instead. In addition, DefMDIChildProc also handles the following messages:

Message	Response
WM_CHILDACTIVATE	Performs activation processing when MDI child windows are sized, moved, or displayed. This message must be passed.
WM_GETMINMAXINFO	Calculates the size of a maximized MDI child window, based on the current size of the MDI client window.
WM_MENUCHAR	Passes the message to the MDI frame window.
WM_MOVE	Recalculates MDI client scroll bars if they are present.
WM_SETFOCUS	Activates the child window if it is not the active MDI child window.
WM_SIZE	Performs operations necessary for changing the size of a window, especially for maximizing or restoring an MDI child window. Failing to pass this message to the DefMDIChildProc function produces highly undesirable results.
WM_SYSCOMMAND	Handles System menu commands: SC_NEXTWINDOW, SC_PREVWINDOW, SC_MOVE, SC_SIZE, and SC_MAXIMIZE.
See Also

DefFrameProc, DefWindowProc, WM_CHILDACTIVATE, WM_GETMINMAXINFO, WM_MENUCHAR, WM_MOVE, WM_SETFOCUS, WM_SETTEXT, WM_SIZE, WM_SYSCOMMAND


DefScreenSaverProc

The DefScreenSaverProc function provides default processing for any messages that a screen saver application does not process.

LONG DefScreenSaverProc(

HWND  hWnd,	// handle of screen saver window
UINT  msg,	// message
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hWnd

Identifies the screen saver window.

msg

Specifies the message to be processed. The DefScreenSaverProc function responds to messages that affect the screen saver's operation, as detailed in the Remarks section.

If a screen saver application must perform a different action in response to any of these messages, the application's ScreenSaverProc window procedure should process the message.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

The return value specifies the result of the message processing and depends on the message sent.

Remarks

A screen saver application's ScreenSaverProc window procedure should use DefScreenSaverProc instead of the DefWindowProc function to provide default message processing. The DefScreenSaverProc function passes any messages that do not affect screen saver operation to DefWindowProc.

The following table describes how the DefScreenSaverProc processes a variety of window messages:

Message	Action
WM_ACTIVATE, WM_ACTIVATEAPP, WM_NCACTIVATE	Closes the screen saver if the wParam parameter is FALSE. A wParam value of FALSE indicates that the screen saver is losing the input focus. The screen saver is closed by sending a WM_CLOSE message.
WM_SETCURSOR	Removes the cursor from the screen by setting the cursor to NULL.
WM_LBUTTONDOWN, WM_RBUTTONDOWN, WM_MBUTTONDOWN, WM_KEYDOWN, WM_KEYUP, WM_MOUSEMOVE	Calls the PostQuitMessage function to close the screen saver.
WM_DESTROY	Posts a WM_CLOSE message to close the screen saver window.
WM_SYSCOMMAND	Returns FALSE if the wParam parameter of WM_SYSCOMMAND is either SC_CLOSE or SC_SCREENSAVE.
See Also

DefWindowProc, PostQuitMessage, ScreenSaverProc, WM_ACTIVATE, WM_ACTIVATEAPP, WM_CLOSE, WM_DESTROY, WM_KEYDOWN, WM_KEYUP, WM_LBUTTONDOWN, WM_MBUTTONDOWN, WM_MOUSEMOVE, WM_NCACTIVATE, WM_RBUTTONDOWN, WM_SETCURSOR, WM_SYSCOMMAND


DefWindowProc

The DefWindowProc function calls the default window procedure to provide default processing for any window messages that an application does not process. This function ensures that every message is processed. DefWindowProc is called with the same parameters received by the window procedure.

LRESULT DefWindowProc(

HWND  hWnd,	// handle of window
UINT  Msg,	// message identifier
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hWnd

Identifies the window procedure that received the message.

Msg

Specifies the message.

wParam

Specifies additional message information. The content of this parameter depends on the value of the Msg parameter.

lParam

Specifies additional message information. The content of this parameter depends on the value of the Msg parameter.

Return Value

The return value is the result of the message processing and depends on the message.

See Also

CallWindowProc, DefDlgProc, WindowProc


DeleteAce

The DeleteAce function deletes an ACE from an ACL.

An ACE is an access-control entry. An ACL is an access-control list.

BOOL DeleteAce(

PACL  pAcl,	// address of access-control list
DWORD  dwAceIndex	// index of ACE position in ACL
);
Parameters

pAcl

Points to an ACL structure. The ACE specified by the dwAceIndex parameter is removed from this ACL.

dwAceIndex

Specifies the ACE to delete. A value of 0 corresponds to the first ACE in the ACL, 1 to the second ACE, and so on.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application can use the ACL_SIZE_INFORMATION structure retrieved by the GetAclInformation function to discover the size of the ACL and the number of ACEs it contains. The GetAce function retrieves information about an individual ACE.

See Also

ACL, ACL_SIZE_INFORMATION, AddAccessAllowedAce, AddAccessDeniedAce, AddAce, AddAuditAccessAce, GetAce, GetAclInformation


DeleteAtom

The DeleteAtom function decrements the reference count of a local string atom. If the atom's reference count is reduced to zero, DeleteAtom removes the string associated with the atom from the local atom table.

ATOM DeleteAtom(

ATOM  nAtom	// atom to delete
);
Parameters

nAtom

Identifies the atom and character string to be deleted.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is the nAtom parameter. To get extended error information, call GetLastError.

Remarks

A string atom's reference count specifies the number of times the atom has been added to or removed from the atom table. The AddAtom function increments the count on each call. 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


DeleteColorSpace  (preliminaryWindows 95)
DeleteColorSpace  (preliminary−Windows 95)

The DeleteColorSpace function deletes the specified color space, freeing all internal resources associated with it.

BOOL DeleteColorSpace(

HCOLORSPACE hColorSpace
);
Parameters

hColorSpace

Handle to the color space to delete.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


DeleteCriticalSection

The DeleteCriticalSection function releases all resources used by an unowned critical section object.

VOID DeleteCriticalSection(

LPCRITICAL_SECTION  lpCriticalSection	// address of critical section object
);
Parameters

lpCriticalSection

Points to the critical section object.

Return Value

This function does not return a value.

Remarks

Deleting a critical section object releases all system resources used by the object. Once deleted, the critical section object cannot be specified in the EnterCriticalSection or LeaveCriticalSection function.

See Also

EnterCriticalSection, InitializeCriticalSection, LeaveCriticalSection


DeleteDC

The DeleteDC function deletes the specified device context (DC).

BOOL DeleteDC(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

An application must not delete a device context whose handle was obtained by calling the GetDC function. Instead, it must call the ReleaseDC function to free the device context.

See Also

CreateDC, GetDC, ReleaseDC


DeleteEnhMetaFile

The DeleteEnhMetaFile function deletes an enhanced-format metafile or an enhanced-format metafile handle.

BOOL DeleteEnhMetaFile(

HENHMETAFILE  hemf	// handle of an enhanced metafile
);
Parameters

hemf

Identifies an enhanced metafile.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

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


DeleteFile

The DeleteFile function deletes an existing file.

BOOL DeleteFile(

LPCTSTR  lpFileName	// address of name of file to delete
);
Parameters

lpFileName

Points to a null-terminated string that specifies the file to be deleted.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If an application attempts to delete an open file or a file that does not exist, the DeleteFile function fails. To close an open file, use the CloseHandle function.

See Also

CloseHandle, CreateFile


DeleteForm

The DeleteForm function removes a form name from the list of supported forms.

BOOL DeleteForm(

HANDLE  hPrinter,	// handle of printer object
LPTSTR  pFormName	// address of form name
);
Parameters

hPrinter

Indicates the open printer handle that this function is to be performed upon.

pFormName

Points to the form name to be removed.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The printer handle is obtained by calling the OpenPrinter function. DeleteForm can only delete form names that were added by using the AddForm function.

See Also

AddForm, OpenPrinter


DeleteMenu

The DeleteMenu function deletes an item from the specified menu. If the menu item 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.

BOOL DeleteMenu(

HMENU  hMenu,	// handle of menu
UINT  uPosition,	// menu item identifier or position
UINT  uFlags	// menu item flag
);
Parameters

hMenu

Identifies the menu to be changed.

uPosition

Specifies the menu item to be deleted, as determined by the uFlags parameter.

uFlags

Specifies how the uPosition parameter is interpreted. This parameter must be one of the following values:

Value	Meaning
MF_BYCOMMAND	Indicates that uPosition gives the identifier of the menu item. The MF_BYCOMMAND flag is the default flag if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION	Indicates that uPosition gives the zero-based relative position of the menu item.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

See Also

DrawMenuBar, RemoveMenu


DeleteMetaFile

The DeleteMetaFile function deletes a Windows-format metafile or Windows-format metafile handle.

This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the DeleteEnhMetaFile function.

BOOL DeleteMetaFile(

HMETAFILE  hmf	// handle of Windows-format metafile
);
Parameters

hmf

Identifies a Windows-format metafile.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced format metafile functions.

If the metafile identified by the hmf parameter is stored in memory (rather than on a disk), its content is lost when it is deleted by using the DeleteMetaFile function.

See Also

BeginPath, CopyMetaFile, CreateMetaFile, DeleteEnhMetaFile, GetMetaFile, PolyBezier, SetWorldTransform


DeleteMonitor

The DeleteMonitor function removes a printer monitor added by the AddMonitor function.

BOOL DeleteMonitor(

LPTSTR  pName,	// address of server name
LPTSTR  pEnvironment,	// address of environment string
LPTSTR  pMonitorName	// address of monitor name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server from which the monitor is to be removed. If this parameter is NULL, the printer monitor is removed locally.

pEnvironment

Points to a null-terminated string that specifies the environment from which the monitor is to be removed (for example, "Windows NT x86", "Windows NT R4000", "Windows NT Alpha_AXP", or "Windows 4.0"). If this parameter is NULL, the monitor is removed from the current environment of the calling application and client machine (not of the destination application and print server).

pMonitorName

Points to a null-terminated string that specifies the name of the monitor to be removed.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AddMonitor


DeleteObject

The DeleteObject function deletes a logical pen, brush, font, bitmap, region, or palette, freeing all system resources associated with the object. After the object is deleted, the specified handle is no longer valid.

BOOL DeleteObject(

HGDIOBJ  hObject	// handle of graphic object
);
Parameters

hObject

Identifies a logical pen, brush, font, bitmap, region, or palette.

Return Value

If the function succeeds, the return value is TRUE.

If the given handle is not valid or is currently selected into a device context (DC), the return value is FALSE.

Remarks

The object to be deleted must not be currently selected into a DC.

When a pattern brush is deleted, the bitmap associated with the brush is not deleted. The bitmap must be deleted independently.

See Also

SelectObject


DeletePort

The DeletePort function displays a dialog box that allows the user to delete a port name.

BOOL DeletePort(

LPTSTR  pName,	// address of server name
HWND  hWnd,	// handle of window that displays dialog box
LPTSTR  pPortName	// address of port name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server for which the port should be deleted. If this parameter is NULL, a local port is deleted.

hWnd

Identifies the parent window of the port-deletion dialog box.

pPortName

Points to a null-terminated string that specifies the name of the port that should be deleted.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application can retrieve the names of valid ports by calling the EnumPorts function.

The DeletePort function returns an error if a printer is currently connected to the specified port.

See Also

AddPort, EnumPorts


DeletePrinter

The DeletePrinter function deletes the specified printer object.

BOOL DeletePrinter(

HANDLE  hPrinter	// handle of printer object
);
Parameters

hPrinter

Identifies a printer object that will be deleted.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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 fails with an InvalidState error.

See Also

AddPrinter, EnumPrinters, OpenPrinter


DeletePrinterConnection

The DeletePrinterConnection function deletes a connection to a printer that was established by a call to AddPrinterConnection or ConnectToPrinterDlg.

BOOL DeletePrinterConnection (

LPTSTR  pName	// address of printer name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the printer connection to delete.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The DeletePrinterConnection function does not delete any printer drivers copied to the server on which the printer resides when the printer connection was established.

See Also

AddPrinterConnection, ConnectToPrinterDlg


DeletePrinterDriver

The DeletePrinterDriver function removes the specified printer-driver name from the list of names of supported drivers for a server.

BOOL DeletePrinterDriver(

LPTSTR  pName,	// address of server name
LPTSTR  pEnvironment,	// address of environment
LPTSTR  pDriverName	// address of driver name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server from which the driver is to be deleted. If this parameter is NULL, the printer-driver name will be removed locally.

pEnvironment

Points to a null-terminated string that specifies the environment from which the driver is to be deleted (for example, "Windows NT x86", "Windows NT R4000", "Windows NT Alpha_AXP", or "Windows 4.0"). If this parameter is NULL, the driver name is deleted from the current environment of the calling application and client machine (not of the destination application and print server).

pDriverName

Points to a null-terminated string specifying the name of the driver that should be deleted.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The DeletePrinterDriver function does not delete the associated files, it merely removes the driver name from the list returned by the EnumPrinterDrivers function.

See Also

EnumPrinterDrivers


DeletePrintProcessor

The DeletePrintProcessor function removes a printer processor added by the AddPrintProcessor function.

BOOL DeletePrintProcessor (

LPTSTR  pName,	// address of server name
LPTSTR  pEnvironment,	// address of environment string
LPTSTR  pPrintProcessorName	// address of processor name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server from which the processor is to be removed. If this parameter is NULL, the printer processor is removed locally.

pEnvironment

Points to a null-terminated string that specifies the environment from which the processor is to be removed (for example, "Windows NT x86", "Windows NT R4000", "Windows NT Alpha_AXP", or "Windows 4.0"). If this parameter is NULL, the processor is removed from the current environment of the calling application and client machine (not of the destination application and print server). NULL is the recommended value, as it provides maximum portability.

pPrintProcessorName

Points to a null-terminated string that specifies the name of the processor to be removed.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AddPrintProcessor


DeletePrintProvidor

The DeletePrintProvidor function removes a printer provider added by the AddPrintProvidor function.

BOOL DeletePrintProvidor (

LPTSTR  pName,	// address of server name
LPTSTR  pEnvironment,	// address of environment string
LPTSTR  pPrintProvidorName	// address of provider name
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server from which the provider is to be removed. If this parameter is NULL, the printer provider is removed locally.

pEnvironment

Points to a null-terminated string that specifies the environment from which the provider is to be removed (for example, "Windows NT x86", "Windows NT R4000", "Windows NT Alpha_AXP", or "Windows 4.0"). If this parameter is NULL, the provider is removed from the current environment of the calling application and client machine (not of the destination application and print server). NULL is the recommended value because it provides maximum portability.

pPrintProvidorName

Points to a null-terminated string that specifies the name of the provider to be removed.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AddPrintProvidor


DeleteService

The DeleteService function marks the specified service for deletion from the service control manager database.

BOOL DeleteService(

SC_HANDLE  hService	// handle of service
);
Parameters

hService

Identifies the service. This handle is returned by the OpenService or CreateService function, and it must have DELETE access.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error codes may be set by the service control manager. Others may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The specified handle was not opened with DELETE access.
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_SERVICE_MARKED_FOR_DELETE	The specified service has already been marked for deletion.
Remarks

The DeleteService function marks a service for deletion from the service control manager database. The database entry is not removed until all open handles to the service have been closed by calls to the CloseServiceHandle function, and the service is not running. A running service is stopped by a call to the ControlService function with the SERVICE_CONTROL_STOP control code. If the service cannot be stopped, the database entry is removed when the system is restarted.

The service control manager deletes the service by deleting the service key and its subkeys from the registry.

See Also

CloseServiceHandle, ControlService, CreateService, OpenService


DeregisterEventSource

The DeregisterEventSource function closes a handle returned by the RegisterEventSource function.

BOOL DeregisterEventSource(

HANDLE  hEventLog	// handle to event log
);
Parameters

hEventLog

Identifies the event log whose handle was returned by RegisterEventSource.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

RegisterEventSource


DestroyAcceleratorTable

The DestroyAcceleratorTable function destroys an accelerator table. Before an application closes, it must use this function to destroy each accelerator table that it created by using the CreateAcceleratorTable function.

BOOL DestroyAcceleratorTable(

HACCEL  hAccel	// handle of accelerator table
);
Parameters

hAccel

Identifies the accelerator table to destroy. This handle must have been created by a call to the CreateAcceleratorTable function.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CopyAcceleratorTable, CreateAcceleratorTable, LoadAccelerators, TranslateAccelerator


DestroyCaret

The DestroyCaret function destroys the caret's current shape, frees the caret from the window, and removes the caret from the screen.

If the caret shape is based on a bitmap, DestroyCaret does not free the bitmap.

BOOL DestroyCaret(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

DestroyCaret destroys the caret only if a window in the current task owns the caret. If a window that is not in the current task owns the caret, DestroyCaret does nothing and returns FALSE.

The caret is a shared resource; there is only one caret in the system. A window should create a caret only when it has the keyboard focus or is active. The window should destroy the caret before losing the keyboard focus or becoming inactive.

See Also

CreateCaret, HideCaret, ShowCaret


DestroyCursor

The DestroyCursor function destroys a cursor created by the CreateCursor function and frees any memory the cursor occupied. Do not use this function to destroy a cursor that was not created with the CreateCursor function.

BOOL DestroyCursor(

HCURSOR  hCursor	// handle of cursor to destroy
);
Parameters

hCursor

Identifies the cursor to be destroyed. The cursor must not be in use.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateCursor


DestroyIcon

The DestroyIcon function destroys an icon and frees any memory the icon occupied.

BOOL DestroyIcon(

HICON  hIcon	// handle of icon to destroy
);
Parameters

hIcon

Identifies the icon to be destroyed. The icon must not be in use.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateIcon


DestroyMenu

The DestroyMenu function destroys the given menu and frees any memory that the menu occupies.

BOOL DestroyMenu(

HMENU  hMenu	// handle of menu to destroy
);
Parameters

hMenu

Identifies the menu to be destroyed.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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, RemoveMenu


DestroyPrivateObjectSecurity

The DestroyPrivateObjectSecurity function deletes a protected server object's security descriptor. This security descriptor must have been created by a call to the CreatePrivateObjectSecurity function.

BOOL DestroyPrivateObjectSecurity(

PSECURITY_DESCRIPTOR  * ObjectDescriptor	// address of pointer to SECURITY_DESCRIPTOR
);
Parameters

ObjectDescriptor

Points to a pointer to the SECURITY_DESCRIPTOR structure to be deleted.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreatePrivateObjectSecurity, GetPrivateObjectSecurity, SECURITY_DESCRIPTOR, SetPrivateObjectSecurity


DestroyPropertySheetPage  (preliminaryWindows NT)
DestroyPropertySheetPage  (preliminary−Windows NT)

The DestroyPropertySheetPage function destroys a property sheet page. An application must call this function for pages that have not been passed to the PropertySheet function.

BOOL DestroyPropertySheetPage(

HPROPSHEETPAGE  hPSPage
);
Parameters

hPSPage

Handle to the property sheet page to delete.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

PropertySheet


DestroyWindow

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.

DestroyWindow also destroys modeless dialog boxes created by the CreateDialog function.

BOOL DestroyWindow(

HWND  hWnd	// handle of window to destroy
);
Parameters

hWnd

Identifies the window to be destroyed.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A thread cannot use DestroyWindow to destroy a window created by a different thread.

If the window being destroyed is a child window that does not have the WS_EX_NOPARENTNOTIFY style, a WM_PARENTNOTIFY message is sent to the parent.

See Also

CreateDialog, CreateWindow, CreateWindowEx, WM_DESTROY, WM_NCDESTROY, WM_PARENTNOTIFY


DeviceCapabilities

The DeviceCapabilities function retrieves the capabilities of a printer device driver.

DWORD DeviceCapabilities(

LPCTSTR  pDevice,	// 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
);
Parameters

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 members in the device-independent portion of the structure are supported by the printer driver.
DC_FILEDEPENDENCIES	Returns a list of files that also need to be loaded when a driver is installed. If the pOutput parameter is NULL, the function returns the number of files. Otherwise, pOutput points to an array of filenames in the form char[chFileName, 64]. Each filename is a null-terminated string.
DC_MAXEXTENT	Returns a 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 pOutput parameter. The width (x-dimension) and length (y-dimension) of a paper size are returned as if the paper were in the DMORIENT_PORTRAIT orientation.
DC_SIZE	Returns the dmSize member of the printer driver's DEVMODE structure.
DC_TRUETYPE	Retrieves the abilities of the driver to use TrueType fonts. The return value can be one or more of the following:
Value	Meaning
DCTT_BITMAP	Device can print TrueType fonts as graphics. (For example, dot-matrix and PCL printers.)
DCTT_DOWNLOAD	Device can download TrueType fonts. (For example, PCL and PostScript printers.)
DCTT_SUBDEV	Device can substitute device fonts for TrueType fonts. (For example, PostScript printers.)
	For DC_TRUETYPE, the pOutput parameter should be NULL.
DC_VERSION	Returns the specification version to which the printer driver conforms.
DC_BINADJUST
DC_EMF_COMPLIANT
DC_DATATYPE_PRODUCED
DC_COLLATE
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.

Return Value

If the function succeeds, the return value depends on the setting of the fwCapability parameter.

If the function fails, the return value is −1.

See Also

DEVMODE, GetDeviceCaps, GetProcAddress, LoadLibrary, POINT


DeviceIoControl

The DeviceIoControl function sends a control code directly to a specified device driver, causing the corresponding device to perform the specified operation.

BOOL DeviceIoControl(

HANDLE  hDevice,	// handle to device of interest
DWORD  dwIoControlCode,	// control code of operation to perform
LPVOID  lpInBuffer,	// pointer to buffer to supply input data
DWORD  nInBufferSize,	// size of input buffer
LPVOID  lpOutBuffer,	// pointer to buffer to receive output data
DWORD  nOutBufferSize,	// size of output buffer
LPDWORD  lpBytesReturned,	// pointer to variable to receive output byte count
LPOVERLAPPED  lpOverlapped	// pointer to overlapped structure for asynchronous operation
);
Parameters

hDevice

Handle to the device that is to perform the operation. Call the CreateFile function to obtain a device handle.

dwIoControlCode

Specifies the control code for the operation. This value identifies the specific operation to be performed and the type of device on which the operation is to be performed. The following values are defined:

Value	Meaning
FSCTL_DISMOUNT_VOLUME	Dismounts a volume.
FSCTL_GET_COMPRESSION	Obtains the compression state of a file or directory
FSCTL_LOCK_VOLUME	Locks a volume.
FSCTL_SET_COMPRESSION	Sets the compression state of a file or directory.
FSCTL_UNLOCK_VOLUME	Unlocks a volume.
IOCTL_DISK_CHECK_VERIFY	Checks for change in a 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	Obtains information on the physical disk's geometry.
IOCTL_DISK_GET_DRIVE_LAYOUT	Provides information about each partition on a disk.
IOCTL_DISK_GET_MEDIA_TYPES	Obtains information about media support.
IOCTL_DISK_GET_PARTITION_INFO	Obtains disk partition information.
IOCTL_DISK_LOAD_MEDIA	Loads media into a device.
IOCTL_DISK_MEDIA_REMOVAL	Enables or disables the 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	Sets the disk partition type.
IOCTL_DISK_VERIFY	Performs logical format of a disk extent.
IOCTL_SERIAL_LSRMST_INSERT	Enables or disables placement of a line and modem status data into the data stream.
For more detailed information on each control code, see its topic. In particular, each topic provides details on the usage of the lpInBuffer, nInBufferSize, lpOutBuffer, nOutBufferSize, and lpBytesReturned parameters.

lpInBuffer

Pointer to a buffer that contains the data required to perform the operation.

This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not require input data.

nInBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpInBuffer.

lpOutBuffer

Pointer to a buffer that receives the operation's output data.

This parameter can be NULL if the dwIoControlCode parameter specifies an operation that does not produce output data.

nOutBufferSize

Specifies the size, in bytes, of the buffer pointed to by lpOutBuffer.

lpBytesReturned

Pointer to a variable that receives the size, in bytes, of the data stored into the buffer pointed to by lpOutBuffer.

This parameter cannot be NULL. Even when an operation produces no output data, and lpOutBuffer can be NULL, the DeviceIoControl function makes use of the variable pointed to by lpBytesReturned. After such an operation, the value of the variable is without meaning.

lpOverlapped

Pointer to an OVERLAPPED structure to be used for asynchronous operations.

This parameter is ignored if the handle identified by hDevice was opened without specifying the FILE_FLAG_OVERLAPPED flag.

This parameter can be NULL if an overlapped (asynchronous) operation is not desired.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the lpOverlapped parameter is NULL or the handle identified by hDevice 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 lpOverlapped parameter points to an OVERLAPPED structure and the FILE_FLAG_OVERLAPPED flag was specified when the hDevice handle was opened, DeviceIoControl is performed as an overlapped (asynchronous) operation. In this case, the OVERLAPPED structure must contain a handle to a manual-reset event object (created by using the CreateEvent function).

If the overlapped operation cannot be completed immediately, the function returns FALSE, and GetLastError returns the ERROR_IO_PENDING value, indicating that the operation is executing in the background. When this happens, the operating system sets the event object in the OVERLAPPED structure to the nonsignaled state before DeviceIoControl returns. The system then sets the event object to the signaled state when the operation has been completed. The calling thread can use any of the wait functions to determine the state of the event object, then use the GetOverlappedResult function to determine the results of the operation. The GetOverlappedResult function reports the success or failure of the operation and the number of bytes returned in the lpOutBuffer buffer.

See Also

CreateEvent, CreateFile, GetOverlappedResult, OVERLAPPED, WaitForMultipleObjects, WaitForSingleObject


DialogBox

The DialogBox function creates a modal dialog box from a dialog box template resource. DialogBox does not return control until the specified callback function terminates the modal dialog box by calling the EndDialog function.

int DialogBox(

HANDLE  hInstance,	// handle of application instance
LPCTSTR  lpTemplate,	// identifies dialog box template
HWND  hWndParent,	// handle of owner window
DLGPROC  lpDialogFunc	// address of dialog box procedure
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the dialog box template.

lpTemplate

Identifies the dialog box template. This parameter is either the 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.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see the DialogProc callback function.

Return Value

If the function succeeds, the return value is the nResult parameter in the call to the EndDialog function used to terminate the dialog box.

If the function fails, the return value is −1.

Remarks

The 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 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 box procedure when it called EndDialog.

See Also

CreateDialog, CreateWindowEx, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, DialogProc, EndDialog, MAKEINTRESOURCE, WM_INITDIALOG, WM_SETFONT


DialogBoxIndirect

The DialogBoxIndirect function creates a modal dialog box from a dialog box template in memory. The DialogBoxIndirect function does not return control until the specified callback function terminates the modal dialog box by calling the EndDialog function.

int DialogBoxIndirect(

HANDLE  hInstance,	// handle of application instance
LPDLGTEMPLATE  lpTemplate,	// identifies dialog box template
HWND  hWndParent,	// handle of owner window
DLGPROC  lpDialogFunc	// address of dialog box procedure
);
Parameters

hInstance

Identifies the instance of the module that creates the dialog box.

lpTemplate

Specifies the address of a global memory object that contains a dialog box template used to create the dialog box. The template is in the form of a DLGTEMPLATE structure followed by one or more DLGITEMTEMPLATE structures.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see the description of the DialogProc callback function.

Return Value

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.

If the function fails, the return value is −1.

Remarks

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 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 box procedure when it called EndDialog.

See Also

CreateWindowEx, DialogBox, DialogBoxIndirectParam, DialogBoxParam, DialogProc, DLGTEMPLATE, DLGITEMTEMPLATE, EndDialog, WM_INITDIALOG, WM_SETFONT


DialogBoxIndirectParam

The DialogBoxIndirectParam function creates a modal dialog box from a dialog box template in memory. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

int DialogBoxIndirectParam(

HINSTANCE  hInstance,	// handle of application instance
LPCDLGTEMPLATE  hDialogTemplate,	// identifies dialog box template
HWND  hWndParent,	// handle of owner window
DLGPROC  lpDialogFunc,	// address of dialog box procedure
LPARAM  dwInitParam	// initialization value
);
Parameters

hInstance

Identifies the instance of the module that creates the dialog box.

hDialogTemplate

Specifies the address of a global memory object that contains a dialog box template used to create the dialog box. The template is in the form of a DLGTEMPLATE structure followed by one or more DLGITEMTEMPLATE structures.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see the DialogProc callback function.

dwInitParam

Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Value

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.

If the function fails, the return value is −1.

Remarks

The DialogBoxIndirectParam function uses the CreateWindowEx function to create the dialog box. DialogBoxIndirectParam then sends a WM_INITDIALOG message (and a WM_SETFONT message if the template specifies the DS_SETFONT style) to the dialog box procedure. The function displays the dialog box (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.

When the dialog box procedure calls the EndDialog function, 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 box procedure when it called EndDialog.

See Also

CreateWindowEx, DialogBox, DialogBoxIndirect, DialogBoxParam, DialogProc, DLGTEMPLATE, DLGITEMTEMPLATE, EndDialog, WM_INITDIALOG, WM_SETFONT


DialogBoxParam

The DialogBoxParam function creates a modal dialog box from a dialog box template resource. Before displaying the dialog box, the function passes an application-defined value to the dialog box procedure as the lParam parameter of the WM_INITDIALOG message. An application can use this value to initialize dialog box controls.

int DialogBoxParam(

HINSTANCE  hInstance,	// handle of application instance
LPCTSTR  lpTemplateName,	// identifies dialog box template
HWND  hWndParent,	// handle of owner window
DLGPROC  lpDialogFunc,	// address of dialog box procedure
LPARAM  dwInitParam	// initialization value
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the dialog box template.

lpTemplateName

Identifies the dialog box template. This parameter is either the 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.

hWndParent

Identifies the window that owns the dialog box.

lpDialogFunc

Points to the dialog box procedure. For more information about the dialog box procedure, see the DialogProc callback function.

dwInitParam

Specifies the value to pass to the dialog box in the lParam parameter of the WM_INITDIALOG message.

Return Value

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.

If the function fails, the return value is −1.

Remarks

The DialogBoxParam function uses the CreateWindowEx function to create the dialog box. DialogBoxParam then sends a WM_INITDIALOG message (and a WM_SETFONT message if the template specifies the DS_SETFONT style) to the dialog box procedure. The function displays the dialog box (regardless of whether the template specifies the WS_VISIBLE style), disables the owner window, and starts its own message loop to retrieve and dispatch messages for the dialog box.

When the dialog box procedure calls the EndDialog function, DialogBoxParam destroys the dialog box, ends the message loop, enables the owner window (if previously enabled), and returns the nResult parameter given by the dialog box procedure when it called EndDialog.

See Also

CreateWindowEx, DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogProc, EndDialog, MAKEINTRESOURCE, WM_INITDIALOG, WM_SETFONT


DialogProc

The DialogProc function is an application-defined callback function that processes messages sent to a modal or modeless dialog box.

BOOL CALLBACK DialogProc(

HWND  hwndDlg,	// handle of dialog box
UINT  uMsg,	// message
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hwndDlg

Identifies the dialog box.

uMsg

Specifies the message.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

Except in response to the WM_INITDIALOG message, the dialog box procedure should return nonzero if it processes the message, and zero if it does not. In response to a WM_INITDIALOG message, the dialog box procedure should return zero if it calls the SetFocus function to set the focus to one of the controls in the dialog box. Otherwise, it should return nonzero, in which case the system sets the focus to the first control in the dialog box that can be given the focus.

Remarks

You should use the dialog box procedure only if you use the dialog box class for the dialog box. This is the default class and is used when no explicit class is 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


DisableThreadLibraryCalls

The DisableThreadLibraryCalls function disables the DLL_THREAD_ATTACH and DLL_THREAD_DETACH notifications for the dynamic-link library (DLL) specified by hLibModule. This can reduce the size of the working code set for some applications.

BOOL DisableThreadLibraryCalls(

HMODULE  hLibModule	// dynamic-link library for which calls are to be disabled
);
Parameters

hLibModule

Specifies the dynamic-link library module for which the DLL_THREAD_ATTACH and DLL_THREAD_DETACH notifications are to be disabled.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. The DisableThreadLibraryCalls function fails if the DLL specified by hLibModule has active static thread local storage, or if hLibModule is an invalid module handle. To get extended error information, call GetLastError.

Remarks

The DisableThreadLibraryCalls function lets a DLL disable the DLL_THREAD_ATTACH and DLL_THREAD_DETACH notification calls. This can be a useful optimization for multithreaded applications that have many DLLs, frequently create and delete threads, and whose DLLs do not need these thread-level notifications of attachment/detachment. A remote procedure call (RPC) server application is an example of such an application. In these sorts of applications, DLL initialization routines often remain in memory to service DLL_THREAD_ATTACH and DLL_THREAD_DETACH notifications. By disabling the notifications, the DLL initialization code is not paged in because a thread is created or deleted, thus reducing the size of the application's working code set. To implement the optimization, modify a DLL's DLL_PROCESS_ATTACH code to call DisableThreadLibraryCalls.

See Also

FreeLibraryAndExitThread


DisconnectNamedPipe

The DisconnectNamedPipe function disconnects the server end of a named pipe instance from a client process.

BOOL DisconnectNamedPipe(

HANDLE  hNamedPipe	// handle of named pipe
);
Parameters

hNamedPipe

Identifies an instance of a named pipe. This handle must be created by the CreateNamedPipe function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the client end of the named pipe is open, the DisconnectNamedPipe function forces that end of the named pipe closed. The client receives an error the next time it attempts to access the pipe. A client that is forced off a pipe by DisconnectNamedPipe must still use the CloseHandle function to close its end of the pipe.

When the server process disconnects a pipe instance, any unread data in the pipe is discarded. Before disconnecting, the server can make sure data is not lost by calling the FlushFileBuffers function, which does not return until the client process has read all the data.

The server process must call DisconnectNamedPipe to disconnect a pipe handle from its previous client before the handle can be connected to another client by using the ConnectNamedPipe function.

See Also

CloseHandle, ConnectNamedPipe, CreateNamedPipe, FlushFileBuffers


DispatchMessage

The DispatchMessage function dispatches a message to a window procedure. It is typically used to dispatch a message retrieved by the GetMessage function.

LONG DispatchMessage(

CONST MSG  * lpmsg	// address of structure with message
);
Parameters

lpmsg

Points to an MSG structure that contains the message.

Return Value

The return value specifies the value returned by the window procedure. Although its meaning depends on the message being dispatched, the return value generally is ignored.

Remarks

The MSG structure must contain valid message values. If the lpmsg parameter points to a WM_TIMER message and the lParam parameter of the WM_TIMER message is not NULL, lParam points to a function that is called instead of the window procedure.

See Also

GetMessage, MSG, PeekMessage, PostAppMessage, PostMessage, TranslateMessage, WM_TIMER


DlgDirList

The DlgDirList function fills the specified list box with the names of all files matching the specified path or filename.

int DlgDirList(

HWND  hDlg,	// handle of dialog box with list box
LPTSTR  lpPathSpec,	// address of path or filename string
int  nIDListBox,	// identifier of list box
int  nIDStaticPath,	// identifier of static control
UINT  uFileType	// file attributes to display
);
Parameters

hDlg

Identifies the dialog box that contains the list box.

lpPathSpec

Points to a null-terminated string that contains the path or filename. DlgDirList modifies this string, which should be long enough to contain the modifications. For more information about this parameter, see the Remarks section.

nIDListBox

Specifies the identifier of a list box. If this parameter is zero, DlgDirList assumes that no list box exists and does not attempt to fill one.

nIDStaticPath

Specifies the identifier of the static control used for displaying the current drive and directory. If this parameter is zero, DlgDirList assumes that no such control is present.

uFileType

Specifies attributes of the filenames to be displayed. This parameter must be one or more of the following values:

Value	Description
DDL_ARCHIVE	Includes archived files.
DDL_DIRECTORY	Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).
DDL_DRIVES	Includes drives. Drives are listed in the form [-x-], where x is the drive letter.
DDL_EXCLUSIVE	Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.
DDL_HIDDEN	Includes hidden files.
DDL_READONLY	Includes read-only files.
DDL_READWRITE	Includes read-write files with no additional attributes.
DDL_SYSTEM	Includes system files.
DDL_POSTMSGS	Posts messages to the application's message queue. By default, DlgDirList sends messages directly to the dialog box procedure.
Return Value

If a listing is made — even an empty listing — the return value is nonzero. If the input string does not contain a valid search path, the return value is zero.

Remarks

If you specify a zero-length string for the lpPathSpec parameter or if you specify only a directory name with no filename, the string will be changed to *.*

The lpPathSpec parameter has the following form:

[drive:] [[\u]directory[\idirectory]\u] [filename]

In this example, drive is a drive letter, directory is a valid directory name, and filename is a valid filename that must contain at least one wildcard (? or *).

If lpPathSpec includes a drive or directory name, or both, the current drive and directory are changed to the specified drive and directory before the list box is filled. The static control identified by the nIDStaticPath parameter is also updated with the new drive or directory name, or both.

After the list box is filled, DlgDirList updates lpPathSpec by removing the drive or directory portion, or both, of the path and filename.

DlgDirList sends the LB_RESETCONTENT and LB_DIR messages to the list box.

See Also

DlgDirListComboBox, DlgDirSelectComboBoxEx, DlgDirSelectEx


DlgDirListComboBox

The DlgDirListComboBox function fills the specified combo box with a directory listing. It fills the list with the names of all files, drives, and subdirectories that match the specified attributes and path string.

int DlgDirListComboBox(

HWND  hDlg,	// handle 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
);
Parameters

hDlg

Identifies the dialog box that contains the combo box.

lpPathSpec

Points to a null-terminated string of the following form:

[drive:][\]][directory\[...]][filename]

If the specified string includes a drive or directory path, the DlgDirListComboBox function changes the current drive and directory before filling the list. After the list is filled, the drive and directory path are removed from the string specified by the lpPathSpec parameter.

nIDComboBox

Specifies the identifier of a combo box control in a dialog box. If nIDComboBox is zero, the DlgDirListComboBox function assumes no combo box exists and does not attempt to fill it.

nIDStaticPath

Specifies the identifier of the static text control in which the DlgDirListComboBox function is to display the current directory. If nIDStaticPath is zero, DlgDirListComboBox assumes no such control is present.

uFiletype

Specifies the attributes of the files to be displayed. It can be any combination of the following values:

Value	Meaning
DDL_ARCHIVE	Includes archived files.
DDL_DIRECTORY	Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).
DDL_DRIVES	Includes drives. Drives are listed in the form [-x-], where x is the drive letter.
DDL_EXCLUSIVE	Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.
DDL_HIDDEN	Includes hidden files.
DDL_READONLY	Includes read-only files.
DDL_READWRITE	Includes read-write files with no additional attributes.
DDL_SYSTEM	Includes system files.
DDL_POSTMSGS	Posts messages to the application's message queue. By default, the DlgDirList function sends messages directly to the dialog box procedure.
Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. For example, if the string specified by lpPathSpec is not a valid path, the function fails. To get extended error information, call GetLastError.

Remarks

If the lpszPathSpec parameter points to a zero-length string or to a string specifying a drive, directory, or both — but no filename — the filename *.* (wildcards) is assumed.

See Also

DlgDirList, DlgDirSelectComboBoxEx, DlgDirSelectEx


DlgDirSelect

The DlgDirSelect function is not implemented in the Win32 API. Win32-based applications should use the DlgDirSelectEx function.


DlgDirSelectComboBox

The DlgDirSelectComboBox function is not implemented in the Win32 API. Win32-based applications should use the DlgDirSelectComboBoxEx function.


DlgDirSelectComboBoxEx

The DlgDirSelectComboBoxEx function retrieves the current selection from a combo box filled by using the DlgDirListComboBox function. The selection is interpreted as a drive letter, a file, or a directory name.

BOOL DlgDirSelectComboBoxEx(

HWND  hDlg,	// handle of dialog box with list box
LPTSTR  lpString,	// address of buffer for path string
int  nCount,	// number of characters in path string
int  nIDComboBox	// identifier of combo box
);
Parameters

hDlg

Identifies the dialog box that contains the combo box.

lpString

Points to the buffer that is to receive the selected path.

nCount

Specifies the length, in characters, of the buffer pointed to by the lpString parameter.

nIDComboBox

Specifies the integer identifier of the combo box control in the dialog box.

Return Value

If the current selection is a directory name, the return value is nonzero; otherwise, it is zero. To get extended error information, call GetLastError.

Remarks

If the current selection specifies a directory name or drive letter, the DlgDirSelectComboBoxEx function removes the enclosing square brackets (and hyphens for drive letters) so the name or letter is ready to be inserted into a new path or filename. If there is no selection, the contents of the buffer pointed to by lpString do not change.

The DlgDirSelectComboBox function does not allow more than one filename to be returned from a combo box.

DlgDirSelectComboBoxEx sends CB_GETCURSEL and CB_GETLBTEXT messages to the combo box.

In the Win32 API, you can use this function with all three types of combo boxes (CBS_SIMPLE, CBS_DROPDOWN, and CBS_DROPDOWNLIST).

See Also

CB_GETCURSEL, CB_GETLBTEXT DlgDirListComboBox, DlgDirSelectEx


DlgDirSelectEx

The DlgDirSelectEx function retrieves the current selection from a single-selection list box. It assumes that the list box has been filled by the DlgDirList function and that the selection is a drive letter, filename, or directory name.

BOOL DlgDirSelectEx(

HWND  hDlg,	// handle of dialog box with list box
LPTSTR  lpString,	// address of buffer for path string
int  nCount,	// number of characters in path string
int  nIDListBox	// identifier of list box
);
Parameters

hDlg

Identifies the dialog box that contains the list box.

lpString

Points to a buffer that is to receive the selected path.

nCount

Specifies the length, in characters, of the buffer pointed to by lpString.

nIDListBox

Specifies the integer identifier of a list box in the dialog box.

Return Value

If the current selection is a directory name, the return value is nonzero; otherwise, it is zero. To get extended error information, call GetLastError.

Remarks

The DlgDirSelectEx function copies the selection to the buffer pointed to by the lpString parameter. If the current selection is a directory name or drive letter, DlgDirSelectEx removes the enclosing square brackets (and hyphens, for drive letters), so that the name or letter is ready to be inserted into a new path. If there is no selection, lpString does not change.

DlgDirSelectEx sends LB_GETCURSEL and LB_GETTEXT messages to the list box. The function does not allow more than one filename to be returned from a list box. The list box must not be a multiple-selection list box. If it is, this function does not return a zero value and lpString remains unchanged.

See Also

DlgDirList, DlgDirListComboBox, DlgDirSelectComboBoxEx, LB_GETCURSEL, LB_GETTEXT


DllEntryPoint

The DllEntryPoint function is an optional method of entry into a dynamic-link library (DLL). If the function is used, it is called by the system when processes and threads are initialized and terminated, or upon calls to the LoadLibrary and FreeLibrary functions. DllEntryPoint is a placeholder for the library-defined function name. The actual name must be specified on the linker command line by the -entry switch.

BOOL WINAPI DllEntryPoint(

HINSTANCE  hinstDLL,	// handle of DLL module
DWORD  fdwReason,	// reason for calling function
LPVOID  lpvReserved	// reserved
);
Parameters

hinstDLL

Identifies a handle to the DLL. This handle can be used in subsequent calls to the GetModuleFileName function and other module functions.

fdwReason

Specifies a flag indicating why the DLL entry-point function is being called. This parameter can be one of the following values:

Value	Meaning
DLL_PROCESS_ATTACH
	Indicates that the DLL is attaching to the address space of the current process as a result of the process starting up or as a result of a call to LoadLibrary. DLLs can use this opportunity to initialize any instance data or to use the TlsAlloc function to allocate a thread local storage (TLS) index.
	During initial process startup or after a call to LoadLibrary, the operating system scans the list of loaded DLLs for the process. For each DLL that has not already been called with the DLL_PROCESS_ATTACH value, the system calls the DLL's entry-point function. This call is made in the context of the thread that caused the process address space to change, such as the primary thread of the process or the thread that called LoadLibrary.
DLL_THREAD_ATTACH
	Indicates that the current process is creating a new thread. When this occurs, the system calls the entry-point function of all DLLs currently attached to the process. The call is made in the context of the new thread. DLLs can use this opportunity to initialize a TLS slot for the thread. A thread calling the DLL entry-point function with the DLL_PROCESS_ATTACH value does not call the DLL entry-point function with the DLL_THREAD_ATTACH value.
	Note that a DLL's entry-point function is called with this value only by threads created after the DLL is attached to the process. When a DLL is attached by LoadLibrary, existing threads do not call the entry-point function of the newly loaded DLL.
DLL_THREAD_DETACH
	Indicates that a thread is exiting cleanly. If the DLL has stored a pointer to allocated memory in a TLS slot, it uses this opportunity to free the memory. The operating system calls the entry-point function of all currently loaded DLLs with this value. The call is made in the context of the exiting thread. There are cases in which the entry-point function is called for a terminating thread even if the DLL never attached to the thread — for example, the entry-point function was never called with the DLL_THREAD_ATTACH value in the context of the thread in either of these two situations:
•	The thread was the initial thread in the process, so the system called the entry-point function with the DLL_PROCESS_ATTACH value.

•	The thread was already running when a call to the LoadLibrary function was made, so the system never called the entry-point function for it.

DLL_PROCESS_DETACH
	Indicates that the DLL is detaching from the address space of the calling process as a result of either a clean process exit or of a call to FreeLibrary. The DLL can use this opportunity to call the TlsFree function to free any TLS indices allocated by using TlsAlloc and to free any thread local data. When a DLL detaches from a process as a result of process termination or as a result of a call to FreeLibrary, the operating system does not call the DLL's entry-point function with the DLL_THREAD_DETACH value for the individual threads of the process. The DLL is only given DLL_PROCESS_DETACH notification. DLLs can take this opportunity to clean up all resources for all threads attached and known to the DLL.
lpvReserved

Specifies further aspects of DLL initialization and cleanup.

If fdwReason is DLL_PROCESS_ATTACH, lpvReserved is NULL for dynamic loads and non-NULL for static loads.

If fdwReason is DLL_PROCESS_DETACH, lpvReserved is NULL if DllEntryPoint has been called by using FreeLibrary and non-NULL if DllEntryPoint has been called during process termination.

Return Value

When the system calls the DllEntryPoint function with the DLL_PROCESS_ATTACH value, the function returns TRUE if it succeeds or FALSE if initialization fails. If the return value is FALSE when DllEntryPoint is called because the process uses the LoadLibrary function, LoadLibrary returns NULL. If the return value is FALSE when DllEntryPoint is called during process initialization, the process terminates with an error. To get extended error information, call GetLastError.

When the system calls the DllEntryPoint function with any value other than DLL_PROCESS_ATTACH, the return value is ignored.

See Also

FreeLibrary, GetModuleFileName, LoadLibrary, TlsAlloc, TlsFree


DocumentProperties

The DocumentProperties function retrieves or modifies printer initialization information or displays a printer-configuration dialog box for the specified printer.

LONG DocumentProperties(

HWND  hWnd,	// handle of window that displays dialog box
HANDLE  hPrinter,	// handle of printer object
LPTSTR  pDeviceName,	// address of device name
PDEVMODE  pDevModeOutput,	// address of modified device mode structure
PDEVMODE  pDevModeInput,	// address of original device mode structure
DWORD  fMode	// mode flag
);
Parameters

hWnd

Identifies the parent window of the printer-configuration dialog box.

hPrinter

Identifies a printer object.

pDeviceName

Points to a null-terminated string that specifies the name of the device for which the printer-configuration dialog box should be displayed.

pDevModeOutput

Points to a DEVMODE structure that receives the printer configuration data specified by the user.

pDevModeInput

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 pDevModeInput parameter. The function updates the structure only for those members specified by the DEVMODE structure's dmFields member. This value is also defined as DM_MODIFY. In cases of conflict during the merge, the settings in the DEVMODE structure specified by pDevModeInput override the printer driver's current print settings.
DM_IN_PROMPT	Input value. The function presents the printer driver's Print Setup dialog box and then changes the settings in the printer's DEVMODE data structure to those values specified by the user. This value is also defined as DM_PROMPT.
DM_OUT_BUFFER	Output value. The function writes the printer driver's current print settings, including private data, to the DEVMODE data structure specified by the pDevModeOutput parameter. The caller must allocate a buffer sufficiently large to contain the information. If the bit DM_OUT_BUFFER sets is clear, the pDevModeOutput parameter can be NULL. This value is also defined as DM_COPY.
Return Value

If the fMode parameter is zero, the return value is the size of the buffer required to contain the printer driver initialization data. Note that this buffer can be larger than a DEVMODE structure if the printer driver appends private data to the structure.

If the function displays the initialization dialog box, the return value is either IDOK or IDCANCEL, depending on which button the user selects.

If the function does not display the dialog box and is successful, the return value is IDOK.

If the function fails, the return value is less than zero.

Remarks

The printer object handle identified by the hPrinter parameter can be obtained by calling the OpenPrinter function.

The string pointed to by the pDeviceName parameter can be obtained by calling the GetPrinter function.

Note that the DEVMODE structure actually used by a printer driver contains the device-independent part (as defined above) followed by a driver-specific part that varies in size and content with each driver and driver version. Because of this driver dependence, it is very important for applications to query the driver for the correct size of the DEVMODE structure before allocating a buffer for it.

To make changes to print settings that are local to an application, an application should follow these steps:

1.	Get the number of bytes required for the full DEVMODE structure by calling DocumentProperties and specifying zero in the fMode parameter.

2.	Allocate memory for the full DEVMODE structure.

3.	Get the current printer settings by calling DocumentProperties. Pass a pointer to the DEVMODE structure allocated in Step 2 as the pDevModeOutput parameter and specify the DM_OUT_BUFFER value.

4.	Modify the appropriate members of the returned DEVMODE structure and indicate which members were changed by setting the corresponding bits in the dmFields member of the DEVMODE.

5.	Call DocumentProperties and pass the modified DEVMODE structure back as both the pDevModeInput and pDevModeOutput parameters and specify both the DM_IN_BUFFER and DM_OUT_BUFFER values (which are combined using the OR operator).

The DEVMODE structure returned by the third call to DocumentProperties can be used as an argument in a call to the CreateDC function.

To create a handle of a printer-device context using the current printer settings, you only need to call DocumentProperties twice, as described above. The first call gets the size of the full DEVMODE and the second call initializes the DEVMODE with the current printer settings. Pass the initialized DEVMODE to CreateDC to obtain the handle of the printer device context.

See Also

AdvancedDocumentProperties, CreateDC, DEVMODE, GetPrinter, OpenPrinter


DOS3Call

The DOS3Call function is not implemented in the Win32 API. Win32-based applications cannot call MS-DOS directly.


DosDateTimeToFileTime

The DosDateTimeToFileTime function converts MS-DOS date and time values to a 64-bit file time.

BOOL DosDateTimeToFileTime(

WORD  wFatDate,	// 16-bit MS-DOS date
WORD  wFatTime,	// 16-bit MS-DOS time
LPFILETIME  lpFileTime	// address of buffer for 64-bit file time
);
Parameters

wFatDate

Specifies the MS-DOS date. The date is a packed 16-bit value with the following format:

Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, and so on)
9−15	Year offset from 1980 (add 1980 to get actual year)
wFatTime

Specifies the MS-DOS time. The time is a packed 16-bit value with the following format:

Bits	Contents
0−4	Second divided by 2
5−10	Minute (0−59)
11−15	Hour (0−23 on a 24-hour clock)
lpFileTime

Points to a FILETIME structure to receive the converted 64-bit file time.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

FILETIME, FileTimeToDosDateTime, FileTimeToSystemTime, SystemTimeToFileTime


DPtoLP

The DPtoLP function converts device coordinates into logical coordinates. The conversion depends on the mapping mode of the device context (DC), the settings of the origins and extents for the window and viewport, and the world transformation.

BOOL DPtoLP(

HDC  hdc,	// handle of device context
LPPOINT  lpPoints,	// address of array of points
int  nCount	// count of points
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

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


DragAcceptFiles

The DragAcceptFiles function registers whether a window accepts dropped files.

VOID DragAcceptFiles(

HWND  hWnd,	// handle of the registering window
BOOL  fAccept	// acceptance option
);
Parameters

hWnd

Identifies the window registering whether it accepts dropped files.

fAccept

Specifies whether the window identified by the hWnd parameter accepts dropped files. This value is TRUE to accept dropped files; it is FALSE to discontinue accepting dropped files.

Return Value

This function does not return a value.

Remarks

An application that calls DragAcceptFiles with the fAccept parameter set to TRUE has identified itself as able to process the WM_DROPFILES message from File Manager.

See Also

WM_DROPFILES


DragDetect

The DragDetect function captures the mouse and tracks its movement until the user releases the left button, presses the ESC key, or moves the mouse outside the "drag rectangle" around the given point. The width and height of the drag rectangle are specified by the SM_CXDRAG and SM_CYDRAG values returned by the GetSystemMetrics function.

BOOL DragDetect(

HWND  hwnd,
POINT  pt
);
hwnd

Handle of the window receiving mouse input.

pt

Initial position of the mouse, in screen coordinates. The function determines the coordinates of the drag rectangle by using this point.

Return Value

If the user moved the mouse outside of the drag rectangle while holding the left button down, the return value is TRUE.

If the user did not move the mouse outside of the drag rectangle while holding the left button down, the return value is FALSE.

Remarks

The system metrics for the drag rectangle are configurable, allowing for larger or smaller drag rectangles.

See Also

GetSystemMetrics


DragFinish

The DragFinish function releases memory that Windows allocated for use in transferring filenames to the application.

VOID DragFinish(

HDROP  hDrop	// handle of memory to free
);
Parameters

hDrop

Identifies the structure describing dropped files. This handle is retrieved from the wParam parameter of the WM_DROPFILES message.

Return Value

This function does not return a value.

See Also

WM_DROPFILES


DragQueryFile

The DragQueryFile function retrieves the filenames of dropped files.

UINT DragQueryFile(

HDROP  hDrop,	// handle of structure for dropped files
UINT  iFile,	// index of file to query
LPTSTR  lpszFile,	// buffer for returned filename
UINT  cch	// size of buffer for filename
);
Parameters

hDrop

Identifies the structure containing the filenames of the dropped files.

iFile

Specifies the index of the file to query. If the value of the iFile parameter is 0xFFFFFFFF, DragQueryFile returns a count of the files dropped. If the value of the iFile parameter is between zero and the total number of files dropped, DragQueryFile copies the filename with the corresponding value to the buffer pointed to by the lpszFile parameter.

lpszFile

Points to a buffer to receive the filename of a dropped file when the function returns. This filename is a null-terminated string. If this parameter is NULL, DragQueryFile returns the required size, in characters, of the buffer.

cch

Specifies the size, in characters, of the lpszFile buffer.

Return Value

When the function copies a filename to the buffer, the return value is a count of the characters copied, not including the terminating null character.

If the index value is 0xFFFFFFFF, the return value is a count of the dropped files.

If the index value is between zero and the total number of dropped files and the lpszFile buffer address is NULL, the return value is the required size, in characters, of the buffer, not including the terminating null character.

See Also

DragQueryPoint


DragQueryPoint

The DragQueryPoint function retrieves the position of the mouse pointer at the time a file was dropped.

BOOL DragQueryPoint(

HDROP  hDrop,	// handle of structure for dropped file
LPPOINT  lppt	// address of structure for mouse coordinates
);
Parameters

hDrop

Identifies the structure describing the dropped file.

lppt

Points to a POINT structure that the function fills with the coordinates of the mouse pointer at the time the file was dropped.

Return Value

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


DrawAnimatedRects  (preliminaryWindows 95)
DrawAnimatedRects  (preliminary−Windows 95)

The DrawAnimatedRects function draws a wire-frame rectangle and animates it to indicate the opening of an icon or the minimizing or maximizing of a window.

BOOL WINAPI DrawAnimatedRects(

HWND hwnd,	// handle of clipping window
int idAni,	// type of animation
CONST RECT * lprcFrom,	// address of rectangle coordinates (minimized)
CONST RECT * lprcTo	// address of rectangle coordinates (restored)
);
Parameters

hwnd

Handle of the window to which the rectangle is clipped. If this parameter is NULL, the working area of the screen is used.

idAni

Specifies the type of animation to perform. This parameter can be one of these values:

Value	Meaning
IDANI_OPEN	Draws the animated rectangle beginning with the position specified by the lprcFrom parameter and ending with the position specified by the lprcTo parameter.
IDANI_CLOSE	Draws the animated rectangle beginning with the position specified by the lprcTo parameter and ending with the position specified by the lprcFrom parameter.
lprcFrom

Points to a SMALL_RECT structure specifying the location and size of the icon or minimized window. Coordinates are relative to the rectangle specified by the lprcClip parameter.

lprcTo

Points to a SMALL_RECT structure specifying the location and size of the restored window. Coordinates are relative to the rectangle specified by the lprcClip parameter.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

SMALL_RECT


DrawCaption  (preliminaryWindows 95)
DrawCaption  (preliminary−Windows 95)

The DrawCaption function draws a window caption.

void WINAPI DrawCaption(

HDC hdc,	// handle of device context
LPRECT lprc,	// address of bounding rectangle coordinates
HFONT hfont,	// handle of font for caption
HICON hicon,	// handle of icon in caption
LPSTR lpszText,	// address of caption string
WORD wFlags	// drawing options
);
Parameters

hdc

Identifies the device context.

lprc

Points to a RECT structure specifying the bounding rectangle for the window caption.

hfont

Identifies the font to use for caption text. To use the standard font, specify NULL for this parameter.

hicon

Identifies the icon to display in the caption. This parameter can be NULL.

lpszText

Points to a null-terminated string containing the caption text. This parameter can be NULL.

wFlags

Specifies drawing options. This parameter can be zero or more of the following values:

Value	Meaning
DC_ACTIVE	Uses the colors for an active caption.
DC_SMALLCAP	Draws a small caption. Uses the current small caption font if the hfont parameter is NULL.
If DC_SMALLCAP is specified, the function draws a normal window caption.

Return Value

This function does not return a value.

See Also

RECT


DrawEdge  (preliminaryWindows NT)
DrawEdge  (preliminary−Windows NT)

The DrawEdge function draws one or more edges of rectangle.

BOOL DrawEdge(

HDC hdc,	// handle of device context
LPRECT qrc,	// address of rectangle coordinates
UINT edge,	// type of inner and outer edge to draw
UINT grfFlags	// type of border
);
Parameters

hdc

Identifies the device context.

qrc

Points to a RECT structure that contains the logical coordinates of the rectangle.

edge

Specifies the type of inner and outer edge to draw. This parameter must be a combination of one inner-border flag and one outer-border flag. The inner-border flags are as follows:

Value	Meaning
BDR_RAISEDINNER	Raised inner edge.
BDR_SUNKENINNER	Sunken inner edge.
The outer-border flags are as follows:

Value	Meaning
BDR_RAISEDOUTER	Raised outer edge.
BDR_SUNKENOUTER	Sunken outer edge.
Alternatively, the edge parameter can specify one of the following flags:

Value	Meaning
EDGE_BUMP	Combination of BDR_RAISEDOUTER and BDR_SUNKENINNER.
EDGE_ETCHED	Combination of BDR_SUNKENOUTER and BDR_RAISEDINNER.
EDGE_RAISED	Combination of BDR_RAISEDOUTER and BDR_RAISEDINNER.
EDGE_SUNKEN	Combination of BDR_SUNKENOUTER and BDR_SUNKENINNER.
grfFlags

Specifies the type of border. This parameter can be a combination of these values:

Value	Meaning
BF_ADJUST	Rectangle to be adjusted to leave space for client area.
BF_BOTTOM	Bottom of border rectangle.
BF_BOTTOMLEFT	Bottom and left side of border rectangle.
BF_BOTTOMRIGHT	Bottom and right side of border rectangle.
BF_DIAGONAL	Diagonal border.
BF_DIAGONAL_ENDBOTTOMLEFT	Diagonal border. The end point is the bottom-left corner of the rectangle; the origin is top-right corner.
BF_DIAGONAL_ENDBOTTOMRIGHT	Diagonal border. The end point is the bottom-right corner of the rectangle; the origin is top-left corner.
BF_DIAGONAL_ENDTOPLEFT	Diagonal border. The end point is the top-left corner of the rectangle; the origin is bottom-right corner.
BF_DIAGONAL_ENDTOPRIGHT	Diagonal border. The end point is the top-right corner of the rectangle; the origin is bottom-left corner.
BF_FLAT	Flat border.
BF_LEFT	Left side of border rectangle.
BF_MIDDLE	Interior of rectangle to be filled.
BF_MONO	One-dimensional border.
BF_RECT	Entire border rectangle.
BF_RIGHT	Right side of border rectangle.
BF_SOFT	Soft buttons instead of tiles.
BF_TOP	Top of border rectangle.
BF_TOPLEFT	Top and left side of border rectangle.
BF_TOPRIGHT	Top and right side of border rectangle.
Return Value

If the function succeeds, the return value is TRUE.

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

See Also

RECT


DrawEscape

The DrawEscape function accesses drawing capabilities of a video display that are not directly available through the graphics device interface (GDI).

int DrawEscape(

HDC  hdc,	// handle of device context
int  nEscape,	// specifies escape function
int  cbInput,	// size of structure for input
LPCSTR  lpszInData	// address of structure for input
);
Parameters

hdc

Identifies the device context for the specified video display.

nEscape

Specifies the escape function to be performed.

cbInput

Specifies the number of bytes of data pointed to by the lpszInData parameter.

lpszInData

Points to the input structure required for the specified escape.

Return Value

The return value specifies the outcome of the function. It is greater than zero if the function is successful, except for the QUERYESCSUPPORT draw escape, which checks for implementation only. The return value is zero if the escape is not implemented. The return value is less than zero if an error occurred. To get extended error information, call GetLastError.

Remarks

When an application calls the DrawEscape function, the data identified by cbInput and lpszInData is passed directly to the specified display driver.


DrawFocusRect

The DrawFocusRect function draws a rectangle in the style used to indicate that the rectangle has the focus.

BOOL DrawFocusRect(

HDC  hDC,	// handle of device context
CONST RECT  * lprc	// address of structure for rectangle
);
Parameters

hDC

Identifies the device context.

lprc

Points to a RECT structure that specifies the logical coordinates of the rectangle.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Because DrawFocusRect is an XOR function, calling it a second time with the same rectangle removes the rectangle from the screen.

This function draws a rectangle that cannot be scrolled. To scroll an area containing a rectangle drawn by this function, call DrawFocusRect to remove the rectangle from the screen, scroll the area, and then call DrawFocusRect again to draw the rectangle in the new position.

See Also

FrameRect, RECT


DrawFrameControl  (preliminaryWindows NT)
DrawFrameControl  (preliminary−Windows NT)

The DrawFrameControl function draws a frame control of the specified type and style.

BOOL DrawFrameControl(

HDC  hdc,	// handle of device context
LPRECT  lprc,	// address of bounding rectangle
UINT  uType,	// frame-control type
UINT  uState	// frame-control state
);
Parameters

hdc

Identifies the device context of the window in which to draw the control.

lprc

Points to a RECT structure that contains the logical coordinates of the bounding rectangle for frame control.

uType

Specifies the type of frame control to draw. This parameter can be one of the following values:

Value	Meaning
DFC_BUTTON	Standard button
DFC_CAPTION	Title bar
DCF_MENU	Menu
DFC_SCROLL	Scroll bar
uState

Specifies the initial state of the frame control. If uType is DFC_BUTTON, uState can be one of the following values:

Value	Meaning
DFCS_BUTTON3STATE	Three-state button
DFCS_BUTTONCHECK	Check box
DFCS_BUTTONPUSH	Push button
DFCS_BUTTONRADIO	Radio button
DFCS_BUTTONRADIOIMAGE	Image for radio button (nonsquare needs image)
DFCS_BUTTONRADIOMASK	Mask for radio button (nonsquare needs mask)
If uType is DFC_CAPTION, uState can be one of the following values:

Value	Meaning
DFCS_CAPTIONCLOSE	Close button
DFCS_CAPTIONHELP	Windows 95 only: Help button
DFCS_CAPTIONMAX	Maximize button
DFCS_CAPTIONMIN	Minimize button
DFCS_CAPTIONRESTORE	Restore button
If uType is DFC_MENU, uState can be one of the following values:

Value	Meaning
DFCS_MENUARROW	Submenu arrow
DFCS_MENUBULLET	Bullet
DFCS_MENUCHECK	Check mark
If uType is DFC_SCROLL, uState can be one of the following values:

Value	Meaning
DFCS_SCROLLCOMBOBOX	Combo box scroll bar
DFCS_SCROLLDOWN	Down arrow of scroll bar
DFCS_SCROLLLEFT	Left arrow of scroll bar
DFCS_SCROLLRIGHT	Right arrow of scroll bar
DFCS_SCROLLSIZEGRIP	Size grip in bottom-right corner of window
DFCS_SCROLLUP	Up arrow of scroll bar
The following style can be used to adjust the bounding rectangle of the push button:

Value	Meaning
DFCS_ADJUSTRECT	Bounding rectangle is adjusted to exclude the surrounding edge of the push button.
One or more of the following values can be used to set the state of the control to be drawn:

Value	Meaning
DFCS_CHECKED	Button is checked.
DFCS_FLAT	Button has a flat border.
DFCS_INACTIVE	Button is inactive (grayed).
DFCS_MONO	Button has a monochrome border.
DFCS_PUSHED	Button is pushed.
Return Value

If the function succeeds, the return value is TRUE.

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

See Also

RECT


DrawIcon

The DrawIcon function draws an icon in the client area of the window of the specified device context .

BOOL DrawIcon(

HDC  hDC,	// handle 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
);
Parameters

hDC

Identifies the device context for a window.

X

Specifies the logical x-coordinate of the upper-left corner of the icon.

Y

Specifies the logical y-coordinate of the upper-left corner of the icon.

hIcon

Identifies the icon to be drawn.

Windows NT: The icon resource must have been previously loaded by using the LoadIcon function.

Windows 95: The icon resource must have been previously loaded by using the LoadIcon or LoadImage functions.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

DrawIcon places the icon's upper-left corner at the location specified by the X and Y parameters. The location is subject to the current mapping mode of the device context.

See Also

CreateIcon, DrawIconEx, LoadIcon


DrawIconEx  (preliminaryWindows NT)
DrawIconEx  (preliminary−Windows NT)

The DrawIconEx function draws an icon or cursor in the client area of the window of the given device context, performing the specified raster operations, and stretching or compressing the icon or cursor as specified.

BOOL DrawIconEx(

HDC  hdc,	// handle of device context
int  xLeft,	// x-coordinate of upper left corner
int  yTop,	// y-coordinate of upper left corner
HICON  hIcon,	// handle of icon to draw
int  cxWidth,	// width of the icon
int  cyWidth,	// height of the icon
UINT  istepIfAniCur,	// index of frame in animated cursor
HBRUSH  hbrFlickerFreeDraw,	// handle of background brush
UINT  diFlags	// icon-drawing flags
);
Parameters

hdc

Identifies the device context for a window.

xLeft

Specifies the logical x-coordinate of the upper-left corner of the icon or cursor.

yTop

Specifies the logical y-coordinate of the upper-left corner of the icon or cursor.

hIcon

Identifies the icon or cursor to be drawn. This parameter can identify an animated cursor. The icon or cursor resource must have been previously loaded by using the LoadImage function.

cxWidth

Specifies the logical width of the icon or cursor.

cyWidth

Specifies the logical height of the icon or cursor.

istepIfAniCur

Specifies the index of the frame to draw, if hIcon identifies an animated cursor. This parameter is ignored if hIcon does not identify an animated cursor.

hbrFlickerFreeDraw

Identifies a brush that the system uses for flicker-free drawing. If hbrBkgnd is a valid brush handle, the system creates an offscreen bitmap using the given brush for the background color, draws the icon or cursor into the bitmap, and then copies the bitmap into the device context identified by hdc. If hbrBkgnd is NULL, the system draws the icon or cursor directly into the device context.

diFlags

Specifies the drawing flags. This parameter can be one of the following values:

Value	Meaning
DI_COMPAT	Draws the icon or cursor using the system default image rather than the user-specified image.
DI_DEFAULTSIZE	Draws the icon or cursor in its default width, ignoring the cxWidth and cyWidth parameters.
DI_IMAGE	Performs the raster operation specified by ropImage.
DI_MASK	Performs the raster operation specified by ropMask.
DI_NORMAL	Combination of DI_IMAGE and DI_MASK.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

DrawIconEx places the icon's upper-left corner at the location specified by the xLeft and yTop parameters. The location is subject to the current mapping mode of the device context.

See Also

CopyImage, DrawIcon, LoadImage


DrawInsert  (preliminaryWindows NT)
DrawInsert  (preliminary−Windows NT)

The DrawInsert function draws the insert icon in the parent window of the specified drag list box.

void DrawInsert(

HWND  handParent,
HWND  hLB,
int  nItem
);
Parameters

handParent

Handle to the parent window of the drag list box.

hLB

Handle to the drag list box.

nItem

Identifier of the icon item to be drawn.

Return Value

This function does not return a value.


DrawMenuBar

The DrawMenuBar function redraws the menu bar of the specified window. If the menu bar changes after Windows has created the window, this function must be called to draw the changed menu bar.

BOOL DrawMenuBar(

HWND  hWnd	// handle of window with menu bar to redraw
);
Parameters

hWnd

Identifies the window whose menu bar needs redrawing.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

DeleteMenu, InsertMenuItem, RemoveMenu, SetMenuItemInfo


DrawState  (preliminaryWindows 95)
DrawState  (preliminary−Windows 95)

The DrawState function displays an image and applies a visual effect to indicate a state, such as a disabled or default state.

BOOL WINAPI DrawState(

HDC hdc,	// handle of device context
HBRUSH hbr,	// handle of brush
DRAWSTATEPROC lpOutputFunc,	// address of callback function
LPARAM lData,	// image information
WPARAM wData,	// more image information
int x,	// horizontal location of image
int y,	// vertical location of image
int cx,	// width of image
int cy,	// height of image
UINT fuFlags	// image type and state
);
Parameters

hdc

Identifies the device context to draw in.

hbr

Identifies the brush used to draw the image, if the state specified by the fuFlags parameter is DSS_MONO. This parameter is ignored for other states.

lpOutputFunc

Points to an application-defined callback function used to render the image. This parameter is required if the image type in fuFlags is DST_COMPLEX. It is optional and can be NULL if the image type is DST_TEXT. For all other image types, this parameter is ignored. For more information about the callback function, see the DrawStateProc function.

lData

Specifies information about the image. The meaning of this parameter depends on the image type.

wData

Specifies information about the image. The meaning of this parameter depends on the image type. It is, however, zero extended for use with the DrawStateProc function.

x

Specifies the horizontal location at which to draw the image.

y

Specifies the vertical location at which to draw the image.

cx

Specifies the width of the image, in device units. This parameter is required if the image type is DST_COMPLEX. Otherwise, it can be zero to calculate the width of the image.

cy

Specifies the height of the image, in device units. This parameter is required if the image type is DST_COMPLEX. Otherwise, it can be zero to calculate the height of the image.

fuFlags

Specifies the image type and state. The type can be one of these values:

Value (type)	Meaning
DST_BITMAP	The image is a bitmap. The low-order word of the lData parameter is the bitmap handle.
DST_COMPLEX	The image is application defined. To render the image, DrawState calls the callback function specified by the lpOutputFunc parameter.
DST_ICON	The image is an icon. The low-order word of lData is the icon handle.
DST_PREFIXTEXT	The image is text that may contain an accelerator mnemonic. DrawState interprets the ampersand (&) prefix character as a directive to underscore the character that follows. The lData parameter specifies the address of the string, and the wData parameter specifies the length. If wData is zero, the string must be null-terminated.
DST_TEXT	The image is text. The lData parameter specifies the address of the string, and the wData parameter specifies the length. If wData is zero, the string must be null-terminated.
The state can be one of these values:

Value (state)	Meaning
DSS_NORMAL	Draws the image without any modification.
DSS_UNION	Dithers the image.
DSS_DISABLED	Embosses the image.
DSS_DEFAULT	Makes the image bold.
DSS_MONO	Draws the image using the brush specified by the hbr parameter.
For all states except DSS_NORMAL, the image is converted to monochrome before the visual effect is applied.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

DrawStateProc


DrawStateProc  (preliminaryWindows 95)
DrawStateProc  (preliminary−Windows 95)

The DrawStateProc function is an application-defined callback function that renders a complex image for the DrawState function.

BOOL CALLBACK DrawStateProc(

HDC hdc,	// handle of device context
LPARAM lData,	// image information
WPARAM wData,	// more image information
int cx,	// width of image
int cy	// height of image
);
Parameters

hdc

Identifies the device context to draw in. The device context is a memory device context with a bitmap selected, the dimensions of which are at least as great as those specified by the cx and cy parameters.

lData

Specifies information about the image, which the application passed to DrawState.

wData

Specifies information about the image, which the application passed to DrawState.

cx

Specifies the image width, in device units, as specified by the call to DrawState.

cy

Specifies the image height, in device units, as specified by the call to DrawState.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

DrawState


DrawStatusText  (preliminaryWindows NT)
DrawStatusText  (preliminary−Windows NT)

The DrawStatusText function draws the specified text in the style of a status window with borders.

void DrawStatusText(

HDC hdc,
LPRECT  lprc,
LPCTSTR  pszText,
UINT  uFlags
);
Parameters

hdc

Handle to the display context for the window.

lprc

Pointer to a RECT structure that contains the position, in client coordinates, of the rectangle in which the text is drawn. The function draws the borders just inside of the edges of the specified rectangle.

pszText

Pointer to a null-terminated string that specifies the text to display. Tab characters in the string determine whether the string is left-aligned, right-aligned, or centered.

uFlags

Text drawing flags. This parameter can be a combination of these values:

Value	Meaning
SBT_NOBORDERS	Prevents borders from being drawn around the specified text.
SBT_POPOUT	Draws highlighted borders that make the text stand out.
SBT_RTLREADING	Windows 95 only: Displays text using right-to-left reading order on Hebrew or Arabic systems.
Return Value

This function does not return a value.

See Also

RECT


DrawText

The DrawText function draws formatted text in the specified rectangle. It formats the text according to the specified method (expanding tabs, justifying characters, breaking lines, and so forth).

int DrawText(

HDC  hDC,	// handle of device context
LPCTSTR  lpString,	// address of string to draw
int  nCount,	// string length, in characters
LPRECT  lpRect,	// address of structure with formatting dimensions
UINT  uFormat	// text-drawing flags
);
Parameters

hDC

Identifies the device context.

lpString

Points to the string to be drawn. If the nCount parameter is −1, the string must be null-terminated.

nCount

Specifies the number of characters in the string. If nCount is −1, then the lpString parameter is assumed to be a pointer to a null-terminated string and DrawText computes the character count automatically.

lpRect

Points to a RECT structure that contains the rectangle (in logical coordinates) in which the text is to be formatted.

uFormat

Specifies the method of formatting the text. It can be any combination of the following values:

Value	Description
DT_BOTTOM	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 lpRect parameter and extends the base of the rectangle to bound the last line of text. If there is only one line of text, DrawText modifies the right side of the rectangle so that it bounds the last character in the line. In either case, DrawText returns the height of the formatted text but does not draw the text.
DT_CENTER	Centers text horizontally.
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 uFormat parameter specify the number of characters for each tab. The default number of characters per tab is eight.
DT_TOP	Top-justifies text (single line only).
DT_VCENTER	Centers text vertically (single line only).
DT_WORDBREAK	Breaks words. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by the lpRect parameter. A carriage return-linefeed sequence also breaks the line.
Note that the DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, and DT_NOPREFIX values cannot be used with the DT_TABSTOP value.

Return Value

If the function succeeds, the return value is the height of the text.

Remarks

The DrawText function uses the device context's selected font, text color, and background color to draw the text. Unless the DT_NOCLIP format is used, DrawText clips the text so that it does not appear outside the 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


DrawTextEx  (preliminaryWindows 95)
DrawTextEx  (preliminary−Windows 95)

The DrawTextEx function draws formatted text in the specified rectangle.

int DrawTextEx(

HDC hdc,	// handle of device context
LPTSTR lpchText,	// address of string to draw
int cchText,	// length of string to draw
LPRECT lprc,	// address of rectangle coordinates
UINT dwDTFormat,	// formatting options
LPDRAWTEXTPARAMS lpDTParams	// address of structure for more options
);
Parameters

hdc

Identifies the device context to draw in.

lpchText

Points to the string to draw. The string must be null-terminated if the cchText parameter is  −1.

cchText

Specifies the length, in characters, of the string specified by the lpchText parameter. If the string is null-terminated, this parameter can be  −1 to calculate the length.

lprc

Points to a RECT structure that contains the rectangle, in logical coordinates, in which the text is to be formatted.

dwDTFormat

Specifies formatting options. This parameter can be one or more of these values:

Value	Meaning
DT_BOTTOM	Justifies the text to the bottom pf the rectangle. This value must be combined with DT_SINGLELINE.
DT_CALCRECT	Determines the width and height of the rectangle. If there are multiple lines of text, DrawTextEx uses the width of the rectangle pointed to by the lprc parameter and extends the base of the rectangle to bound the last line of text. If there is only one line of text, DrawTextEx modifies the right side of the rectangle so that it bounds the last character in the line. In either case, DrawTextEx returns the height of the formatted text, but does not draw the text.
DT_CENTER	Centers text horizontally in the rectangle.
DT_EDITCONTROL	Duplicates the text-displaying characteristics of a multiline edit control. Specifically, the average character width is calculated in the same manner as for an edit control, and the function does not display a partially visible last line.
DT_END_ELLIPSIS or DT_PATH_ELLIPSIS	Replaces part of the given string with ellipses, if necessary, so that the result fits in the specified  rectangle. The given string is not modified unless the DT_MODIFYSTRING flag is specified. You can specify DT_END_ELLIPSIS to replace characters at the end of the string, or DT_PATH_ELLIPSIS to replace characters in the middle of the string. If the string contains backslash (\) characters, DT_PATH_ELLIPSIS preserves as much as possible of the text after the last backslash.
DT_EXPANDTABS	Expands tab characters. The default number of characters per tab is 8.
DT_EXTERNALLEADING	Includes the font external leading in line height. Normally, external leading is not included in the height of a line of text.
DT_LEFT	Aligns text to the left.
DT_MODIFYSTRING	Modifies the given string to match the displayed text. This flag has no effect unless the DT_END_ELLIPSIS or DT_PATH_ELLIPSIS flag is specified.
DT_NOCLIP	Draws without clipping. DrawTextEx is somewhat faster when DT_NOCLIP is used.
DT_NOPREFIX	Turns off processing of prefix characters. Normally, DrawTextEx interprets the ampersand (&) mnemonic-prefix character as a directive to underscore the character that follows, and the double ampersand (&&) mnemonic-prefix characters as a directive to print a single ampersand. By specifying DT_NOPREFIX, this processing is turned off.
DT_RIGHT	Aligns text to the right.
DT_RTLREADING	Layout in right to left reading order for bi-directional text when the font selected into the hdc is a Hebrew or Arabic. The default reading order for all text is left to right.
DT_SINGLELINE	Displays text on a single line only. Carriage returns and linefeeds do not break the line.
DT_TABSTOP	Sets tab stops. The DRAWTEXTPARAMS structure pointed to by the lpDTParams parameter specifies the number of average character widths per tab stop.
DT_TOP	Top justifies text (single line only).
DT_VCENTER	Centers text vertically (single line only).
DT_WORDBREAK	Breaks words. Lines are automatically broken between words if a word extends past the edge of the rectangle specified by the lprc parameter. A carriage return-linefeed sequence also breaks the line.
dwDTParams

Points to a DRAWTEXTPARAMS structure that specifies additional formatting options. This parameter can be NULL.

Return Value

If the function succeeds, the return value is the text height.

If the function fails, the return value is zero.

See Also

DrawText, DRAWTEXTPARAMS


DuplicateHandle

The DuplicateHandle function duplicates an object handle.

BOOL DuplicateHandle(

HANDLE  hSourceProcessHandle,	// handle of process with handle to duplicate
HANDLE  hSourceHandle,	// handle to duplicate
HANDLE  hTargetProcessHandle,	// handle of process to duplicate to
LPHANDLE  lpTargetHandle,	// address of duplicate handle
DWORD  dwDesiredAccess,	// access for duplicate handle
BOOL  bInheritHandle,	// handle inheritance flag
DWORD  dwOptions	// optional actions
);
Parameters

hSourceProcessHandle

Identifies the process containing the handle to duplicate. The handle must have PROCESS_DUP_HANDLE access.

hSourceHandle

Identifies the handle to duplicate. This is an open object handle that is valid in the context of the source process. For a list of objects whose handles can be duplicated, see the following Remarks section.

hTargetProcessHandle

Identifies the process that is to receive the duplicated handle. The handle must have PROCESS_DUP_HANDLE access.

lpTargetHandle

Points to a variable receiving the value of the duplicate handle. This handle value is valid in the context of the target process. If lpTargetHandle is NULL, the function duplicates the handle, but does not return the duplicate handle value to the caller.

dwDesiredAccess

Specifies the access requested for the new handle. This parameter is ignored if the dwOptions parameter specifies the DUPLICATE_SAME_ACCESS flag. Otherwise, the flags that can be specified depend on the type of object whose handle is being duplicated. For the flags that can be specified for each object type, see the following Remarks section. Note that the new handle can have more access than the original handle.

bInheritHandle

Indicates whether the handle is inheritable. If TRUE, the duplicate handle can be inherited by new processes created by the target process. If FALSE, the new handle cannot be inherited.

dwOptions

Specifies optional actions. This parameter can be zero, or any combination of the following flags:

Value	Meaning
DUPLICATE_CLOSE_SOURCE	Closes the source handle. This occurs regardless of any error status returned.
DUPLICATE_SAME_ACCESS	Ignores the dwDesiredAccess parameter. The duplicate handle has the same access as the source handle.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

DuplicateHandle can be called by either the source process or the target process. It can also be invoked where the source and target process are the same. For example, a process can use DuplicateHandle to create a noninheritable duplicate of an inheritable handle, or a handle with different access than the original handle.

The duplicating process uses the GetCurrentProcess function to get a handle of itself. To get the other process handle, it may be necessary to use some form of interprocess communication (for example, named pipe or shared memory) to communicate the process identifier to the duplicating process. This identifier is then used in the OpenProcess function to open a handle.

If the process that calls DuplicateHandle is not the target process, the duplicating process must use interprocess communication to pass the value of the duplicate handle to the target process.

The duplicate handle is the same object handle as the source handle. This means that the state of the object is the same for both handles. For example, the current file mark for a file handle is always the same for both handles.

DuplicateHandle can duplicate handles to the following types of objects:

Object	Description
Console input	The handle is returned by the CreateFile function when CONIN$ is specified, or by the GetStdHandle function when STD_INPUT_HANDLE is specified. Console handles can be duplicated for use only in the same process.
Console screen buffer	The handle is returned by the CreateFile function when CONOUT$ is specified, or by the GetStdHandle function when STD_OUTPUT_HANDLE is specified. Console handles can be duplicated for use only in the same process.
Event	The handle is returned by the CreateEvent or OpenEvent function.
File or communications device	The handle is returned by the CreateFile function.
File mapping	The handle is returned by the CreateFileMapping function.
Mutex	The handle is returned by the CreateMutex or OpenMutex function.
Pipe	A named pipe handle is returned by the CreateNamedPipe or CreateFile function. An anonymous pipe handle is returned by the CreatePipe function.
Process	The handle is returned by the CreateProcess or OpenProcess function.
Registry key	The handle is returned by the RegCreateKey, RegCreateKeyEx, RegOpenKey, or RegOpenKeyEx function. Note that registry key handles returned by the RegConnectRegistry function cannot be used in a call to DuplicateHandle.
Semaphore	The handle is returned by the CreateSemaphore or OpenSemaphore function.
Thread	The handle is returned by the CreateProcess, CreateThread, or CreateRemoteThread function.
In addition to STANDARD_RIGHTS_REQUIRED, the following access flags can be specified in the dwDesiredAccess parameter for the different object types. Note that the new handle can have more access than the original handle.

Any combination of the following access flags is valid for handles to communications devices, console input, console screen buffers, files, and pipes:

Access	Description
GENERIC_READ	Enables read access.
GENERIC_WRITE	Enables write access.
Any combination of the following access flags is valid for file-mapping objects:

Access	Description
FILE_MAP_ALL_ACCESS	Specifies all possible access flags for the file-mapping object.
FILE_MAP_READ	Enables mapping the object into memory that permits read access.
FILE_MAP_WRITE	Enables mapping the object into memory that permits write access. For write access, PAGE_READWRITE protection must have been specified when the file-mapping object was created by the CreateFileMapping function.
Any combination of the following access flags is valid for mutex objects:

Access	Description
MUTEX_ALL_ACCESS	Specifies all possible access flags for the mutex object.
SYNCHRONIZE	Windows NT: Enables use of the mutex handle in any of the wait functions to acquire ownership of the mutex, or in the ReleaseMutex function to release ownership.
Any combination of the following access flags is valid for semaphore objects:

Access	Description
SEMAPHORE_ALL_ACCESS	Specifies all possible access flags for the semaphore object.
SEMAPHORE_MODIFY_STATE	Enables use of the semaphore handle in the ReleaseSemaphore function to modify the semaphore's count.
SYNCHRONIZE	Windows NT: Enables use of the semaphore handle in any of the wait functions to wait for the semaphore's state to be signaled.
Any combination of the following access flags is valid for event objects:

Access	Description
EVENT_ALL_ACCESS	Specifies all possible access flags for the event object.
EVENT_MODIFY_STATE	Enables use of the event handle in the SetEvent and ResetEvent functions to modify the event's state.
SYNCHRONIZE	Windows NT: Enables use of the event handle in any of the wait functions to wait for the event's state to be signaled.
Any combination of the following access flags is valid for handles to registry keys:

Value	Meaning
KEY_ALL_ACCESS	Specifies all possible flags for the registry key.
KEY_CREATE_LINK	Enables using the handle to create a link to a registry-key object.
KEY_CREATE_SUB_KEY	Enables using the handle to create a subkey of a registry-key object.
KEY_ENUMERATE_SUB_KEYS	Enables using the handle to enumerate the subkeys of a registry-key object.
KEY_EXECUTE	Equivalent to KEY_READ.
KEY_NOTIFY	Enables using the handle to request change notifications for a registry key or for subkeys of a registry key.
KEY_QUERY_VALUE	Enables using the handle to query a value of a registry-key object.
KEY_READ	Combines the STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY values.
KEY_SET_VALUE	Enables using the handle to create or set a value of a registry-key object.
KEY_WRITE	Combines the STANDARD_RIGHTS_WRITE, KEY_SET_VALUE, and KEY_CREATE_SUB_KEY values.
Any combination of the following access flags is valid for process objects:

Access	Description
PROCESS_ALL_ACCESS	Specifies all possible access flags for the process object.
PROCESS_CREATE_PROCESS	Used internally.
PROCESS_CREATE_THREAD	Enables using the process handle in the CreateRemoteThread function to create a thread in the process.
PROCESS_DUP_HANDLE	Enables using the process handle as either the source or target process in the DuplicateHandle function to duplicate a handle.
PROCESS_QUERY_INFORMATION	Enables using the process handle in the GetExitCodeProcess and GetPriorityClass functions to read information from the process object.
PROCESS_SET_INFORMATION	Enables using the process handle in the SetPriorityClass function to set the process's priority class.
PROCESS_TERMINATE	Enables using the process handle in the TerminateProcess function to terminate the process.
PROCESS_VM_OPERATION	Enables using the process handle in the VirtualProtectEx and WriteProcessMemory functions to modify the virtual memory of the process.
PROCESS_VM_READ	Enables using the process handle in the ReadProcessMemory function to read from the virtual memory of the process.
PROCESS_VM_WRITE	Enables using the process handle in the WriteProcessMemory function to write to the virtual memory of the process.
SYNCHRONIZE	Windows NT: Enables using the process handle in any of the wait functions to wait for the process to terminate.
Any combination of the following access flags is valid for thread objects:

Access	Description
SYNCHRONIZE	Windows NT only: Enables using the thread handle in any of the wait functions to wait for the thread to terminate.
THREAD_ALL_ACCESS	Specifies all possible access flags for the thread object.
THREAD_DIRECT_IMPERSONATION	Used internally.
THREAD_GET_CONTEXT	Enables using the thread handle in the GetThreadContext function to read the thread's context.
THREAD_IMPERSONATE	Used internally.
THREAD_QUERY_INFORMATION	Enables using the thread handle in the GetExitCodeThread, GetThreadPriority, and GetThreadSelectorEntry functions to read information from the thread object.
THREAD_SET_CONTEXT	Enables using the thread handle in the SetThreadContext function to set the thread's context.
THREAD_SET_INFORMATION	Enables using the thread handle in the SetThreadPriority function to set the thread's priority.
THREAD_SET_THREAD_TOKEN	Used internally.
THREAD_SUSPEND_RESUME	Enables using the thread handle in the SuspendThread or ResumeThread functions to suspend or resume a thread.
THREAD_TERMINATE	Enables using the thread handle in the TerminateThread function to terminate the thread.
See Also

CloseHandle, CreateEvent, CreateFile, CreateFileMapping, CreateMutex, CreateNamedPipe, CreatePipe, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, GetCurrentProcess, GetExitCodeProcess, GetExitCodeThread, GetPriorityClass, GetStdHandle, GetThreadContext, GetThreadPriority, GetThreadSelectorEntry, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, ReadProcessMemory, RegConnectRegistry, RegCreateKey, RegCreateKeyEx, RegOpenKey, RegOpenKeyEx, ReleaseMutex, ReleaseSemaphore, ResetEvent, ResumeThread, SetEvent, SetPriorityClass, SetThreadContext, SetThreadPriority, SuspendThread, TerminateProcess, TerminateThread, VirtualProtectEx, WriteProcessMemory


DuplicateToken

The DuplicateToken function creates a new access token that duplicates one already in existence.

BOOL DuplicateToken(

HANDLE  ExistingTokenHandle,	// handle of token to duplicate
SECURITY_IMPERSONATION_LEVEL  ImpersonationLevel,	// impersonation level
PHANDLE  DuplicateTokenHandle	// handle of duplicated token
);
Parameters

ExistingTokenHandle

Identifies an access token opened with TOKEN_DUPLICATE access.

ImpersonationLevel

Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that supplies the impersonation level of the new token.

DuplicateTokenHandle

Identifies the duplicate access token when the function returns. This handle has TOKEN_IMPERSONATE and TOKEN_QUERY access to the new token.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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


EditWordBreakProc

An EditWordBreakProc function is an application-defined callback function. A value of type EDITWORDBREAKPROC is a pointer to such a function.

Windows NT: A multiline edit control calls an EditWordBreakProc function whenever the control must break a line of text.

Windows 95: A multiline edit control or a rich edit control calls an EditWordBreakProc function whenever the control must break a line of text.

int CALLBACK EditWordBreakProc(

LPTSTR  lpch,	// address of edit text
int  ichCurrent,	// index of starting point
int  cch,	// length in characters of edit text
int  code	// action to take
);
Parameters

lpch

Points to the text of the edit control.

ichCurrent

Specifies an index to a character position in the buffer of text that identifies the point at which the function should begin checking for a word break.

cch

Specifies the number of characters in the edit control text.

code

Specifies the action to be taken by the callback function. This parameter can be one of the following values:

Value	Action
WB_ISDELIMITER	Checks whether the character at the current position is a delimiter.
WB_LEFT	Looks for the beginning of a word to the left of the current position.
WB_RIGHT	Looks for the beginning of a word to the right of the current position. (This is useful in right-aligned edit controls.)
Windows 95: Additional values for the code parameter are defined for rich edit controls. For a list of these values, see the description of the EM_FINDWORDBREAK message.

Return Value

If the code parameter specifies WB_ISDELIMITER, the return value is nonzero (TRUE) if the character at the current position is a delimiter, or zero if it is not. Otherwise, the return value is an index to the beginning of a word in the buffer of text.

Remarks

A carriage return followed by a linefeed must be treated as a single word by the callback function. Two carriage returns followed by a linefeed also must be treated as a single word.

An application must install the callback function by specifying the address of the callback function in an EM_SETWORDBREAKPROC message.

EditWordBreakProc is a placeholder for an application-defined function name.

See Also

SendMessage, EM_FINDWORDBREAK, EM_SETWORDBREAKPROC


Ellipse

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.

BOOL Ellipse(

HDC  hdc,	// handle of device context
int  nLeftRect,	// x-coord. of bounding rectangle's upper-left corner
int  nTopRect,	// y-coord. of bounding rectangle's upper-left corner
int  nRightRect,	// x-coord. of bounding rectangle's lower-right corner
int  nBottomRect	// y-coord. bounding rectangle's f lower-right corner
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the x-coordinate of the upper-left corner of the bounding rectangle.

nTopRect

Specifies the y-coordinate of the upper-left corner of the bounding rectangle.

nRightRect

Specifies the x-coordinate of the lower-right corner of the bounding rectangle.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the bounding rectangle.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The current position is neither used nor updated by Ellipse.

See Also

Arc, ArcTo


EmptyClipboard

The EmptyClipboard function empties the clipboard and frees handles to data in the clipboard. The function then assigns ownership of the clipboard to the window that currently has the clipboard open.

BOOL EmptyClipboard(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Before calling EmptyClipboard, an application must open the clipboard by using the OpenClipboard function. If the application specifies a NULL window handle when opening the clipboard, EmptyClipboard succeeds but sets the clipboard owner to NULL.

See Also

OpenClipboard, SetClipboardData, WM_DESTROYCLIPBOARD


EnableMenuItem

The EnableMenuItem function enables, disables, or grays the given menu item.

BOOL EnableMenuItem(

HMENU  hMenu,	// handle of menu
UINT  uIDEnableItem,	// menu item to enable, disable, or gray
UINT  uEnable	// menu item flags
);
Parameters

hMenu

Identifies the menu.

uIDEnableItem

Specifies the menu item to be enabled, disabled, or grayed, as determined by the uEnable parameter. This parameter specifies an item in a menu bar or in a pop-up menu.

uEnable

Specifies flags that control the interpretation of the uIDEnableItem parameter and indicate whether the menu item is enabled, disabled, or grayed. This parameter must be a combination of either MF_BYCOMMAND or MF_BYPOSITION and MF_ENABLED, MF_DISABLED, or MF_GRAYED.

Value	Meaning
MF_BYCOMMAND	Indicates that uIDEnableItem gives the identifier of the menu item. If neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified, the MF_BYCOMMAND flag is the default flag.
MF_BYPOSITION	Indicates that uIDEnableItem gives the zero-based relative position of the menu item.
MF_DISABLED	Indicates that the menu item is disabled, but not grayed, so it cannot be selected.
MF_ENABLED	Indicates that the menu item is enabled and restored from a grayed state so that it can be selected.
MF_GRAYED	Indicates that the menu item is disabled and grayed so that it cannot be selected.
Return Value

The return value specifies the previous state of the menu item (it is either MF_DISABLED, MF_ENABLED, or MF_GRAYED). If the menu item does not exist, the return value is 0xFFFFFFFF.

Remarks

An application must use the MF_BYPOSITION flag to specify the correct menu handle. If the menu handle 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 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.

Windows NT: The CreateMenu, InsertMenu, ModifyMenu, and LoadMenuIndirect functions can also set the state (enabled, disabled, or grayed) of a menu item.

Windows 95: The CreateMenu, InsertMenuItem, SetMenuItemInfo, and LoadMenuIndirect functions can also set the state (enabled, disabled, or grayed) of a menu item.

See Also

CreateMenu, GetMenuItemID, InsertMenu, InsertMenuItem, LoadMenuIndirect, ModifyMenu, SetMenuItemInfo, WM_SYSCOMMAND


EnableScrollBar

The EnableScrollBar function enables or disables one or both scroll bar arrows.

BOOL EnableScrollBar(

HWND  hWnd,	// handle of window or scroll bar
UINT  wSBflags,	// scroll bar type flag
UINT  wArrows	// scroll bar arrow flag
);
Parameters

hWnd

Identifies a window or a scroll bar control, depending on the value of the wSBflags parameter.

wSBflags

Specifies the scroll bar type. This parameter can be one of the following values:

Value	Meaning
SB_BOTH	Enables or disables the arrows on the horizontal and vertical scroll bars associated with the 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.
wArrows

Specifies whether the scroll bar arrows are enabled or disabled and indicates which arrows are enabled or disabled. This parameter can be one of the following values:

Value	Meaning
ESB_DISABLE_BOTH	Disables both arrows on a scroll bar.
ESB_DISABLE_DOWN	Disables the down arrow on a vertical scroll bar.
ESB_DISABLE_LEFT	Disables the left arrow on a horizontal scroll bar.
ESB_DISABLE_LTUP	Disables the left arrow on a horizontal scroll bar or the up arrow of a vertical scroll bar.
ESB_DISABLE_RIGHT	Disables the right arrow on a horizontal scroll bar.
ESB_DISABLE_RTDN	Disables the right arrow on a horizontal scroll bar or the down arrow of a vertical scroll bar.
ESB_DISABLE_UP	Disables the up arrow on a vertical scroll bar.
ESB_ENABLE_BOTH	Enables both arrows on a scroll bar.
Return Value

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

The EnableWindow function enables or disables mouse and keyboard input to the specified window or control. When input is disabled, the window does not receive input such as mouse clicks and key presses. When input is enabled, the window receives all input.

BOOL EnableWindow(

HWND  hWnd,	// handle of window
BOOL  bEnable	// flag for enabling or disabling input
);
Parameters

hWnd

Identifies the window to be enabled or disabled.

bEnable

Specifies whether to enable or disable the window. If this parameter is TRUE, the window is enabled. If the parameter is FALSE, the window is disabled.

Return Value

If the window was previously disabled, the return value is TRUE; otherwise, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

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

CreateWindow, CreateWindowEx, IsWindowEnabled, WM_ENABLE


EndDeferWindowPos

The EndDeferWindowPos function simultaneously updates the position and size of one or more windows in a single screen-refreshing cycle.

BOOL EndDeferWindowPos(

HDWP  hWinPosInfo	// handle of internal structure
);
Parameters

hWinPosInfo

Identifies a multiple-window − position structure that contains size and position information for one or more windows. This internal structure is returned by the BeginDeferWindowPos function or by the most recent call to the DeferWindowPos function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

This function sends the WM_WINDOWPOSCHANGING and WM_WINDOWPOSCHANGED messages to each window identified in the internal structure.

See Also

BeginDeferWindowPos, DeferWindowPos, WM_WINDOWPOSCHANGED, WM_WINDOWPOSCHANGING


EndDialog

The EndDialog function destroys a modal dialog box, causing the system to end any processing for the dialog box.

BOOL EndDialog(

HWND  hDlg,	// handle of dialog box
int  nResult	// value to return
);
Parameters

hDlg

Identifies the dialog box to be destroyed.

nResult

Specifies the value to be returned to the application from the function that created the dialog box.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Dialog boxes created by the DialogBox, DialogBoxParam, DialogBoxIndirect, and DialogBoxIndirectParam functions must be destroyed using the EndDialog function. An application calls EndDialog from within the dialog box procedure; the function must not be used for any other purpose.

A dialog box procedure can call EndDialog at any time, even during the processing of the WM_INITDIALOG message. If your application calls the function while WM_INITDIALOG is being processed, the dialog box is destroyed before it is shown and before the input focus is set.

EndDialog does not destroy the dialog box immediately. Instead, it sets a flag and allows the dialog box procedure to return control to the system. The system checks the flag before attempting to retrieve the next message from the application queue. If the flag is set, the system ends the message loop, destroys the dialog box, and uses the value in nResult as the return value from the function that created the dialog box.

See Also

DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, WM_INITDIALOG


EndDoc

The EndDoc function ends a print job. This function replaces the ENDDOC printer escape.

int EndDoc(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context for the print job.

Return Value

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is less than or equal to zero. To get extended error information, call GetLastError.

Remarks

Applications should call EndDoc immediately after finishing a print job.

See Also

StartDoc


EndDocPrinter

The EndDocPrinter function ends a print job for the given printer.

BOOL EndDocPrinter(

HANDLE  hPrinter	// handle of printer object
);
Parameters

hPrinter

Identifies a printer for which the print job should be ended.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

This function returns an error if the print job was not started by calling the StartDocPrinter function.

See Also

StartDocPrinter


EndPage

The EndPage function informs the device that the application has finished writing to a page. This function is typically used to direct the device driver to advance to a new page. This function replaces the NEWFRAME printer escape.

int EndPage(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context for the print job.

Return Value

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is less than or equal to zero. To get extended error information, call GetLastError.

Remarks

Use the ResetDC function to change the device mode, if necessary, after calling the EndPage function. Note that a call to ResetDC resets all device context attributes back to default values.

Windows 3.x: EndPage resets the device context attributes back to default values. You must re-select objects and set up the mapping mode again before printing the next page.

Windows 95: EndPage does not reset the device context attributes. However, the next StartPage call does reset the device context attributes to default values. At that time, you must re-select objects and set up the mapping mode again before printing the next page.

Windows NT: Beginning with Windows NT Version 3.5, neither EndPage or StartPage resets the device context attributes. Device context attributes remain constant across subsequent pages. You do not need to re-select objects and set up the mapping mode again before printing the next page; however, doing so will produce the same results and reduce code differences between Windows 95 and Windows NT.

See Also

ResetDC, StartPage


EndPagePrinter

The EndPagePrinter function indicates the end of one page and the beginning of the next page for the specified printer.

BOOL EndPagePrinter(

HANDLE  hPrinter	// handle of printer object
);
Parameters

hPrinter

Identifies the printer for which the page will be concluded.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The printer-object handle hPrinter is obtained by calling the OpenPrinter function.

Each page in a print job begins with a StartPagePrinter function call and ends with an EndPagePrinter function call. The data for each page is written to the print file by using the WritePrinter function.

See Also

OpenPrinter, StartPagePrinter, WritePrinter


EndPaint

The EndPaint function marks the end of painting in the given window. This function is required for each call to the BeginPaint function, but only after painting is complete.

BOOL EndPaint(

HWND  hWnd,	// handle of window
CONST PAINTSTRUCT  *lpPaint	// address of structure for paint data
);
Parameters

hWnd

Identifies the window that has been repainted.

lpPaint

Points to a PAINTSTRUCT structure that contains the painting information retrieved by BeginPaint.

Return Value

This function always returns TRUE.

Remarks

If the caret was hidden by BeginPaint, EndPaint restores the caret to the screen.

See Also

BeginPaint, PAINTSTRUCT


EndPath

The EndPath function closes a path bracket and selects the path defined by the bracket into the specified device context.

BOOL EndPath(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context into which the new path is selected.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER

See Also

BeginPath


EndUpdateResource

The EndUpdateResource function ends a resource update in an executable file.

BOOL EndUpdateResource(

HANDLE  hUpdate,	// update-file handle
BOOL  fDiscard	// write flag
);
Parameters

hUpdate

Specifies an update handle. This handle is returned by the BeginUpdateResource function.

fDiscard

Specifies whether to write resource updates to an executable file. If this parameter is TRUE, no changes are made to the executable file. If it is FALSE, the changes are made.

Return Value

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.

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

See Also

BeginUpdateResource, UpdateResource


EnhMetaFileProc

The EnhMetaFileProc function is an application-defined callback function that processes enhanced-format metafile records. This function is called by the EnumEnhMetaFile function.

int CALLBACK EnhMetaFileProc(

HDC  hDC,	// handle 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
);
Parameters

hDC

Identifies the device context passed to EnumEnhMetaFile.

lpHTable

Points to a table of handles associated with the graphics objects (pens, brushes, and so on) in the metafile. The first entry contains the enhanced-metafile handle.

lpEMFR

Points to one of the records in the metafile. This record should not be modified. (If modification is necessary, it should be performed on a copy of the record.)

nObj

Specifies the number of objects with associated handles in the handle table.

lpData

Points to any application-supplied data.

Return Value

This function must return a nonzero value to continue enumeration; to stop enumeration, it must return zero.

Remarks

An application must register the callback function by passing its address to the EnumEnhMetaFile function.

EnhMetaFileProc is a placeholder for the application-supplied function name.

See Also

EnumEnhMetaFile


EnterCriticalSection

The EnterCriticalSection function waits for ownership of the specified critical section object. The function returns when the calling thread is granted ownership.

VOID EnterCriticalSection(

LPCRITICAL_SECTION  lpCriticalSection	// address of critical section object
);
Parameters

lpCriticalSection

Points to the critical section object.

Return Value

This function does not return a value.

Remarks

The threads of a single process can use a critical section object for mutual-exclusion synchronization. The process is responsible for allocating the memory used by a critical section object, which it can do by declaring a variable of type CRITICAL_SECTION. Before using a critical section, some thread of the process must call the InitializeCriticalSection function to initialize the object.

To enable mutually exclusive access to a shared resource, each thread calls 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


EnumCalendarInfo

The EnumCalendarInfo function enumerates calendar information for a specified locale. The CalType parameter specifies the type of calendar information to enumerate. The function returns the specified calendar information for all applicable calendars for the locale, or for a single requested calendar, depending on the value of the Calendar parameter.

The EnumCalendarInfo function enumerates the calendar information by calling an application-defined callback function. It passes the callback function a pointer to a string buffer containing the requested calendar information. This continues until either the last applicable calendar is found or the callback function returns FALSE.

BOOL EnumCalendarInfo(

CALINFO_ENUMPROC  lpCalInfoEnumProc,	// pointer to enumeration callback function
LCID  Locale,	// locale whose calendar information is of interest
CALID  Calendar,	// calendar whose information is of interest
CALTYPE  CalType	// type of calendar information of interest
);
Parameters

lpCalInfoEnumProc

Points to an application-defined callback function. For more information, see the EnumCalendarInfoProc callback function.

Locale

Specifies the locale to retrieve calendar information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
Calendar

Specifies the calendar for which information is requested. The following values are defined:

Value	Meaning
ENUM_ALL_CALENDARS	Enumerate all applicable calendars for the locale specified by Locale.
1	Gregorian (localized)
2	Gregorian (English strings always)
3	Japanese era
4	Year of the Republic of China
5	Tangun Era (Korea)
CalType

Indicates the type of calendar information to be returned.  Note that only one CALTYPE value can be specified per call of this function.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_BADDB
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

See Also

EnumCalendarInfoProc, EnumDateFormats


EnumCalendarInfoProc

An EnumCalendarInfoProc function is an application-defined callback function. It is called as a result of a call to the EnumCalendarInfo function, and receives a pointer to a string buffer containing a calendar information string.

BOOL CALLBACK EnumCalendarInfoProc(

LPTSTR  lpCalendarInfoString	// pointer to calendar information string
);
Parameters

lpCalendarInfoString

Pointer to a string buffer containing a null-terminated calendar information string. This string is formatted according to the CALTYPE value passed to EnumCalendarInfo. Note that lpCalendarInfoString should be an LPWSTR for the Unicode (W) version of EnumCalendarInfo, and an LPSTR for the ANSI (A) version of EnumCalendarInfo.

Return Value

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

EnumCalendarInfoProc is a placeholder for an application-defined function name.

An EnumCalendarInfoProc function can carry out any desired task.

An application registers an EnumCalendarInfoProc function by passing its address to the EnumCalendarInfo function.

A value of type CALINFO_ENUMPROC is a pointer to an EnumCalendarInfoProc function.

See Also

EnumCalendarInfo


EnumChildProc

The EnumChildProc function is an application-defined callback function that receives child window handles as a result of a call to the EnumChildWindows function.

BOOL CALLBACK EnumChildProc(

HWND  hwnd,	// handle of child window
LPARAM  lParam	// application-defined value
);
Parameters

hwnd

Identifies a child window of the parent window specified in EnumChildWindows.

lParam

Specifies the application-defined value given in EnumChildWindows.

Return Value

To continue enumeration, the callback function must return TRUE; to stop enumeration, it must return FALSE.

Remarks

The callback function can carry out any desired task.

An application must register this callback function by passing its address to EnumChildWindows. EnumChildProc is a placeholder for the application-defined function name.

See Also

EnumChildWindows


EnumChildWindows

The EnumChildWindows function enumerates the child windows that belong to the specified parent window by passing the handle of each child window, in turn, to an application-defined callback function. EnumChildWindows continues until the last child window is enumerated or the callback function returns FALSE.

BOOL EnumChildWindows(

HWND  hWndParent,	// handle of parent window
WNDENUMPROC  lpEnumFunc,	// address of callback function
LPARAM  lParam	// application-defined value
);
Parameters

hWndParent

Identifies the parent window whose child windows are to be enumerated.

lpEnumFunc

Points to an application-defined callback function. For more information about the callback function, see the EnumChildProc callback function.

lParam

Specifies a 32-bit, application-defined value to be passed to the callback function.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

EnumChildWindows 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 the GetWindow function in a loop. An application that calls GetWindow to perform this task risks being caught in an infinite loop or referencing a handle to a window that has been destroyed.

See Also

EnumChildProc, EnumThreadWindows, EnumWindows, GetWindow


EnumClipboardFormats

The EnumClipboardFormats function lets you enumerate the data formats that are currently available on the clipboard.

Clipboard data formats are stored in an ordered list. To perform an enumeration of clipboard data formats, you make a series of calls to the EnumClipboardFormats function. For each call, the format parameter specifies an available clipboard format, and the function returns the next available clipboard format.

UINT EnumClipboardFormats(

UINT  format	// specifies a known available clipboard format
);
Parameters

format

Specifies a clipboard format that is known to be available.

To start an enumeration of clipboard formats, set format to zero. When format is zero, the function retrieves the first available clipboard format. For subsequent calls during an enumeration, set format to the result of the previous EnumClipboardFormat call.

Return Value

If the function succeeds, the return value is the clipboard format that follows the specified format. In other words, the next available clipboard format.

If the function fails, the return value is zero. To get extended error information, call GetLastError. If the clipboard is not open, the function fails.

If there are no more clipboard formats to enumerate, the return value is zero. In this case, the GetLastError function returns the value NO_ERROR. This lets you distinguish between function failure and the end of enumeration.

Remarks

You must open the clipboard before enumerating its formats. Use the OpenClipboard function to open the clipboard. The EnumClipboardFormats function fails if the clipboard is not open.

The EnumClipboardFormats function enumerates formats in the order that they were placed on the clipboard. If you are copying information to the clipboard, add clipboard objects in order from the most descriptive clipboard format to the least descriptive clipboard format. If you are pasting information from the clipboard, retrieve the first clipboard format that you can handle. That will be the most descriptive clipboard format that you can handle.

The operating system provides automatic type conversions for certain clipboard formats. In the case of such a format, this function enumerates the given format, then enumerates the formats to which it can be converted. For more information about clipboard formats and automatic clipboard format type conversions, see the GetClipboardData and SetClipboardData functions.

See Also

CountClipboardFormats, GetClipboardData, OpenClipboard, RegisterClipboardFormat, SetClipboardData


EnumCodePagesProc

An EnumCodePagesProc function is an application-defined callback function. It is called as a result of a call to the EnumSystemCodePages function, and receives a pointer to a string buffer containing a code page identifier.

BOOL CALLBACK EnumCodePagesProc(

LPTSTR  lpCodePageString	// pointer to code page identifier string
);
Parameters

lpCodePageString

Pointer to a string buffer containing a null-terminated code page identifier string.

Return Value

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

EnumCodePagesProc is a placeholder for an application-defined function name.

An EnumCodePagesProc function can carry out any desired task.

An application registers an EnumCodePagesProc function by passing its address to the EnumSystemCodePages function.

A value of type CODEPAGE_ENUMPROC is a pointer to an EnumCodePagesProc function.

See Also

EnumSystemCodePages


EnumDateFormats

The EnumDateFormats function enumerates the long or short date formats that are available for a specified locale, including date formats for any alternate calendars. The value of the dwFlags parameter determines whether the long or short date formats are enumerated. The function enumerates the date formats by passing date format string pointers, one at a time, to the specified application-defined callback function. This continues until the last date format is found or the callback function returns FALSE.

BOOL EnumDateFormats(

DATEFMT_ENUMPROC  lpDateFmtEnumProc,	// pointer to enumeration callback function
LCID  Locale,	// locale whose date formats are of interest
DWORD  dwFlags	// date formats to enumerate
);
Parameters

lpDateFmtEnumProc

Points to an application-defined callback function. The EnumDateFormats function enumerates date formats by making repeated calls to this callback function. For more information, see the EnumDateFormatsProc callback function.

Locale

Specifies the locale to retrieve date format information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

Specifies the date formats that are of interest. Use one of the following values:

Value	Meaning
DATE_SHORTDATE	Return short date formats.
DATE_LONGDATE	Return long date formats.
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_PARAMETER
ERROR_BADDB
ERROR_INVALID FLAGS

Remarks

The DATE_SHORTDATE and DATE_LONGDATE flags are mutually exclusive. Use one or the other, but not both.

See Also

EnumDateFormatsProc, EnumCalendarInfo, EnumTimeFormats


EnumDateFormatsProc

An EnumDateFormatsProc function is an application-defined callback function. It is called as a result of a call to the EnumDateFormats function, and receives a pointer to a string buffer containing a date format string.

BOOL CALLBACK EnumDateFormatsProc(

LPTSTR  lpDateFormatString	// pointer to date format string
);
Parameters

lpDateFormatString

Pointer to a string buffer containing a null-terminated date format string. This string is a long or short date format, depending on the value of the dwFlags parameter passed to EnumDateFormats. Note that lpDateFormatString should be an LPWSTR for the Unicode (W) version of EnumDateFormats, and an LPSTR for the ANSI (A) version of EnumDateFormats.

Return Value

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

EnumDateFormatsProc is a placeholder for an application-defined function name.

An EnumDateFormatsProc function can carry out any desired task.

An application registers an EnumDateFormatsProc function by passing its address to the EnumDateFormats function.

A value of type DATEFMT_ENUMPROC is a pointer to an EnumDateFormatsProc function.

See Also

EnumDateFormats


EnumDependentServices

The EnumDependentServices function enumerates services that depend on another specified service; that is, the specified service must be running before the enumerated services can run. The name and status of each dependent service are provided.

BOOL EnumDependentServices(

SC_HANDLE  hService,	// handle of service
DWORD  dwServiceState,	// state of services to enumerate
LPENUM_SERVICE_STATUS  lpServices,	// address of service status buffer
DWORD  cbBufSize,	// size of service status buffer
LPDWORD  pcbBytesNeeded,	// address of variable for bytes needed
LPDWORD  lpServicesReturned	// address of variable for number returned
);
Parameters

hService

Handle that identifies the service. This handle is returned by the OpenService or CreateService function, and it must have SERVICE_ENUMERATE_DEPENDENTS access.

dwServiceState

Specifies the services to enumerate based on their running state. It must be one or both of the following values:

Value	Meaning
SERVICE_ACTIVE	Enumerates services that are in the following states: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, and SERVICE_PAUSED.
SERVICE_INACTIVE	Enumerates services that are in the SERVICE_STOPPED state.
lpServices

Pointer to an array of ENUM_SERVICE_STATUS structures. Each structure receives name and service status information for a dependent service. The order of the services in this array is the reverse of the start order of the services. In other words, the first dependent service in the array is the one that would be started last, and the last service in the array is the one that would be started first.

cbBufSize

Specifies the size, in bytes, of the buffer pointed to by the lpServices parameter.

pcbBytesNeeded

Pointer to a variable that receives the number of bytes needed to store the array of service entries. The variable only receives this value if the buffer pointed to by lpServices is too small, indicated by function failure and the ERROR_MORE_DATA error; otherwise, the contents of *pcbBytesNeeded are undefined.

lpServicesReturned

Pointer to a variable that receives the number of service entries returned.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with SERVICE_ENUMERATE_DEPENDENTS access.
ERROR_INVALID_HANDLE
	The specified handle is invalid.
ERROR_INVALID_PARAMETER
	A parameter that was specified is invalid.
ERROR_MORE_DATA
	The buffer pointed to by lpServices is not large enough. The function sets the variable pointed to by lpServicesReturned to the actual number of service entries stored into the buffer. The function sets the variable pointed to by pcbBytesNeeded to the number of bytes required to store all of the service entries.
Remarks

The returned services entries are ordered in the reverse order of the start order, with group order taken into account. If you need to stop the dependent services, you can use the order of entries written to the lpServices buffer to stop the dependent services in the proper order.

See Also

CreateService, ENUM_SERVICE_STATUS, EnumServicesStatus, OpenService


EnumDesktopProc  (preliminaryWindows NT)
EnumDesktopProc  (preliminary−Windows NT)

The EnumDesktopProc function is an application-defined callback function that receives a desktop name as a result of a call to the EnumDesktops function.

BOOL CALLBACK EnumDesktopProc(

LPCSTR lpszDesktop,	// name of a desktop
LPARAM lParam	// value specified in EnumDesktops call
);
Parameters

lpszDesktop

Points to the null-terminated name of a desktop.

lParam

Specifies the application-defined value given in the EnumDesktops function.

Return Value

To continue enumeration, the callback function must return TRUE. To stop enumeration, it must return FALSE.

Remarks

The EnumDesktopProc function is a placeholder for the application-defined function name.

See Also

EnumDesktops


EnumDesktops  (preliminaryWindows NT)
EnumDesktops  (preliminary−Windows NT)

The EnumDesktops function enumerates all desktops in the window station assigned to the calling process. The function does so by passing the name of each desktop, in turn, to an application-defined callback function.

BOOL EnumDesktops(

HWINSTA hwinsta,	// handle of window station to enumerate
DESKTOPENUMPROC lpEnumFunc,	// points to application's callback function
LPARAM lParam	// 32-bit value to pass to the callback function
);
Parameters

hwinsta

Specifies the handle of the window station whose desktops are to be enumerated. The CreateWindowStation, GetProcessWindowStation, and OpenWindowStation functions return a window station handle.

lpEnumFunc

Points to an application-defined EnumDesktopProc callback function.

dwDesiredAccess

Specifies a 32-bit application-defined value to be passed to the callback function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The calling process must have WINSTA_ENUMDESKTOPS access to the window station. The EnumDesktops function enumerates only those desktops for which the calling process has DESKTOP_ENUMERATE access.

The EnumDesktops function repeatedly invokes the lpEnumFunc callback function until the last desktop is enumerated or the callback function returns FALSE.

See Also

CreateWindowStation, EnumDesktopProc, GetProcessWindowStation, OpenWindowStation


EnumDesktopWindows  (preliminaryWindows NT)
EnumDesktopWindows  (preliminary−Windows NT)

The EnumDesktopWindows function enumerates all windows in a desktop by passing the handle of each window, in turn, to an application-defined callback function.

BOOL EnumDesktopWindows(

HDESK hDesktop,	// handle of desktop to enumerate
WNDENUMPROC lpfn,	// points to application's callback function
LPARAM lParam	// 32-bit value to pass to the callback function
);
Parameters

hDesktop

Specifies the handle of the desktop whose windows are to be enumerated. The CreateDesktop, OpenDesktop, and GetThreadDesktop functions return a desktop handle.

lpfn

Points to an application-defined EnumWindowsProc callback function.

lParam

Specifies a 32-bit application-defined value to be passed to the callback function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The EnumDesktopWindows function repeatedly invokes the lpfn callback function until the last window is enumerated or the callback function returns FALSE.

See Also

CreateDesktop, EnumWindowsProc, GetThreadDesktop, OpenDesktop


EnumDisplaySettings  (preliminaryWindows NT)
EnumDisplaySettings  (preliminary−Windows NT)

The EnumDisplaySettings function obtains information about one of a display device's graphics modes. You can obtain information for all of a display device's graphics modes by making a series of calls to this function.

BOOL EnumDisplaySettings(

LPCTSTR lpszDeviceName,	// specifies the display device
DWORD iModeNum,	// specifies the graphics mode
LPDEVMODE lpDevMode	// points to structure to receive settings
);
Parameters

lpszDeviceName

Pointer to a null-terminated string that specifies the display device whose graphics mode the function will obtain information about.

This parameter can be NULL. A NULL value specifies the current display device on the computer that the calling thread is running on.

If lpszDeviceName is not NULL, the string must be of the form \\.\DisplayX, where X can have the values 1, 2, or 3.

Windows 95: lpszDeviceName must be NULL.

iModeNum

Index value that specifies the graphics mode for which information is to be obtained.

Graphics mode indexes start at zero. To obtain information for all of a display device's graphics modes, make a series of calls to EnumDisplaySettings, as follows: Set iModeNum to zero for the first call, and increment iModeNum by one for each subsequent call. Continue calling the function until the return value is FALSE.

When you call EnumDisplaySettings with iModeNum set to zero, the operating system initializes and caches information about the display device. When you call EnumDisplaySettings with iModeNum set to a non-zero value, the function returns the information that was cached the last time the function was called with iModeNum set to zero.

lpDevMode

Pointer to a DEVMODE structure into which the function stores information about the specified graphics mode.

The EnumDisplaySettings function sets values for the following five DEVMODE members:

dmBitsPerPel

dmPelsWidth

dmPelsHeight

dmDisplayFlags

dmDisplayFrequency

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

The function fails if iModeNum is greater than the index of the display device's last graphics mode. As noted in the description of the iModeNum parameter, you can use this behavior to enumerate all of a display device's graphics modes.

See Also

CreateDC, CreateDesktop, DEVMODE


EnumEnhMetaFile

The EnumEnhMetaFile function enumerates the records within an enhanced-format metafile by retrieving each record and passing it to the specified callback function. The application-supplied callback function processes each record as required. The enumeration continues until the last record is processed or when the callback function returns zero.

BOOL EnumEnhMetaFile(

HDC  hdc,	// handle 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
);
Parameters

hdc

Identifies a device context. This handle is passed to the callback function.

hemf

Identifies an enhanced metafile.

lpEnhMetaFunc

Points to the application-supplied callback function. For more information, see the EnhMetaFileProc function.

lpData

Points to optional callback-function data.

lpRect

Points to a RECT structure that specifies the coordinates of the picture's upper-left and lower-right corners. The dimensions of this rectangle are specified in logical units.

Return Value

If the callback function successfully enumerates all the records in the enhanced metafile, the return value is TRUE; otherwise, it is FALSE.

Remarks

Points along the edge of the rectangle pointed to by the lpRect parameter are included in the picture. If the hdc parameter is NULL, Windows ignores lpRect.

If the callback function calls the PlayEnhMetaFileRecord function, hdc must identify a valid device context. Windows uses the device context's transformation and mapping mode to transform the picture displayed by the PlayEnhMetaFileRecord function.

You can use the EnumEnhMetaFile function to embed one enhanced-metafile within another.

See Also

EnhMetaFileProc, PlayEnhMetaFile, PlayEnhMetaFileRecord, RECT


EnumFontFamExProc  (preliminaryWindows 95)
EnumFontFamExProc  (preliminary−Windows 95)

The EnumFontFamExProc function is an application-supplied callback function that processes the fonts enumerated by the EnumFontFamiliesEx function. The system calls this callback function once for each enumerated font.

int CALLBACK EnumFontFamExProc(

ENUMLOGFONTEX * lpelfe,	// address of logical-font data
NEWTEXTMETRICEX * lpntme,	// address of physical-font data
int FontType,	// type of font
LPARAM lParam	// application-defined data
);
Parameters

lpelfe

Points to an ENUMLOGFONTEX structure that contains information about the logical attributes of the font.

lpntme

Points to a structure that contains information about the physical attributes of a font. The function uses the NEWTEXTMETRICEX structure for TrueType fonts; and the TEXTMETRIC structure for other fonts.

FontType

Specifies the type of the font. This parameter can be a combination of these values:

DEVICE_FONTTYPE
RASTER_FONTTYPE
TRUETYPE_FONTTYPE
lParam

Specifies the application-defined data passed by the EnumFontFamiliesEx function.

Return Value

The return value must be a nonzero value to continue enumeration; to stop enumeration, the return value must be zero.

Remarks

Unlike the EnumFontFamProc callback function, EnumFontFamExProc receives extended information about a font. The ENUMLOGFONTEX structure includes the localized name of the script (character set) and the NEWTEXTMETRICEX structure includes a font-coverage signature.

See Also

EnumFontFamiliesEx, EnumFontFamProc, ENUMLOGFONTEX, NEWTEXTMETRICEX, TEXTMETRIC


EnumFontFamilies

The EnumFontFamilies function enumerates the fonts in a specified font family that are available on a specified device. This function supersedes the EnumFonts function.

int EnumFontFamilies(

HDC  hdc,	// handle of device control
LPCTSTR  lpszFamily,	// address of family-name string
FONTENUMPROC  lpEnumFontFamProc,	// address of callback function
LPARAM  lParam	// address of application-supplied data
);
Parameters

hdc

Identifies the device context.

lpszFamily

Points to a null-terminated string that specifies the family name of the desired fonts. If lpszFamily is NULL, EnumFontFamilies randomly selects and enumerates one font of each available type family.

lpEnumFontFamProc

Specifies the procedure-instance address of the application-defined callback function. For information about the callback function, see the EnumFontFamProc function.

lParam

Points to application-supplied data. The data is passed to the callback function along with the font information.

Return Value

If the function succeeds, the return value is the last value returned by the callback function. Its meaning is implementation specific.

Remarks

The EnumFontFamilies function differs from the EnumFonts function in that it retrieves the style names associated with a TrueType font. With EnumFontFamilies, information can be retrieved about unusual font styles (for example, Outline) that could not be enumerated by using the EnumFonts function. Win32-based applications should use EnumFontFamilies instead of EnumFonts.

For each font having the typeface name specified by the lpszFamily parameter, the EnumFontFamilies function retrieves information about that font and passes it to the function pointed to by the lpEnumFontFamProc parameter. The application-defined callback function can process the font information as desired. Enumeration continues until there are no more fonts or the callback function returns zero.

See Also

EnumFontFamProc, EnumFonts


EnumFontFamiliesEx  (preliminaryWindows 95)
EnumFontFamiliesEx  (preliminary−Windows 95)

The EnumFontFamiliesEx function enumerates all fonts in the system that match the font characteristics given by the the LOGFONT structure. EnumFontFamiliesEx enumerates fonts based on typeface name, character set, or both. It is recommended that Win32-based applications use this function rather than EnumFontFamilies to enumerate fonts.

int EnumFontFamiliesEx(

HDC hdc,	// handle of device context
LPLOGFONT lpLogfont,	// address of logical font information
FONTENUMPROC lpEnumFontFamExProc,	// address of callback function
LPARAM lParam,	// application-supplied data
DWORD dwFlags	// reserved; must be zero
);
Parameters

hdc

Identifies the device context.

lpLogfont

Points to a LOGFONT structure that contains information about the fonts to enumerate. The function examines these members:

Member	Description
lfCharset	If set to DEFAULT_CHARSET, the function enumerates all fonts in all character sets. If set to a valid character set value, the function enumerates only fonts in the given character set.
lfFaceName	If set to an empty string, the function enumerates one font in each available typeface name. If set to a valid typeface name, the function enumerates all fonts with the specified name.
lfPitchAndFamily	Must be set to zero for all language versions of the operating system except Hebrew and Arabic. For these languages, set IfPitchAndFamily to MONO_FONT to enumerate only fonts that provide all codepage characters within the font.
lpEnumFontFamExProc

Points to the application-defined callback function. For more information about the callback function, see the EnumFontFamExProc function.

lParam

Specifies a 32-bit application-defined value. The function passes this value to the callback function along with font information.

dwFlags

Reserved; must be zero.

Return Value

If the function succeeds, the return value is the last value returned by the callback function. This value depends on which font families are available for the given device.

Remarks

EnumFontFamiliesEx does not use "tagged" typeface names to identify character sets. Instead, it always passes the correct typeface name and a separate character set value to the callback function. The function enumerates fonts based on the the values of the lfCharset and lfFacename members in the LOGFONT structure.

If lfCharset is DEFAULT_CHARSET and lfFaceName is an empty string, the function enumerates one font in every face in every character set. If lfFaceName is not empty, the function enumerates every font in the specified typeface regardless of character set.

If lfCharset is a valid character set value and lfFaceName is an empty string, the function enumerates every font in the specified character set. If lfFaceName is not empty, the function enumerates every font having the specified typeface and character set.

See Also

EnumFontFamilies, EnumFontFamExProc, LOGFONT


EnumFontFamProc

The EnumFontFamProc function is an application-defined callback function that retrieves data describing available fonts.

int CALLBACK EnumFontFamProc(

ENUMLOGFONT FAR*  lpelf,	// 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
);
Parameters

lpelf

Points to an ENUMLOGFONT structure that contains information about the logical attributes of the font. This structure is locally defined.

lpntm

Points to a NEWTEXTMETRIC structure that contains information about the physical attributes of the font, if the font is a TrueType font. If the font is not a TrueType font, this parameter points to a TEXTMETRIC structure.

FontType

Specifies the type of the font. This parameter can be a combination of the following values:

DEVICE_FONTTYPE
RASTER_FONTTYPE
TRUETYPE_FONTTYPE

lParam

Points to the application-defined data passed by the EnumFontFamilies function.

Return Value

The return value must be a nonzero value to continue enumeration; to stop enumeration, it must return zero.

Remarks

An application must register this callback function by passing its address to the EnumFontFamilies function.

The EnumFontFamProc function is a placeholder for the application-defined function name.

The AND (&) operator can be used with the RASTER_FONTTYPE, DEVICE_FONTTYPE, and TRUETYPE_FONTTYPE constants to determine the font type. If the RASTER_FONTTYPE bit is set, the font is a raster font. If the TRUETYPE_FONTTYPE bit is set, the font is a TrueType font. If neither bit is set, the font is a vector font. DEVICE_FONTTYPE is set when a device (for example, a laser printer) supports downloading TrueType fonts or when the font is a device-resident font; it is zero if the device is a display adapter, dot-matrix printer, or other raster device. An application can also use DEVICE_FONTTYPE to distinguish graphics device interface (GDI)-supplied raster fonts from device-supplied fonts. GDI can simulate bold, italic, underline, and strikeout attributes for GDI-supplied raster fonts, but not for device-supplied fonts.

See Also

EnumFontFamilies, EnumFontFamProc, EnumFonts, ENUMLOGFONT, NEWTEXTMETRIC, TEXTMETRIC


EnumFonts

The EnumFonts function enumerates the fonts available on a specified device. For each font with the specified typeface name, the EnumFonts function retrieves information about that font and passes it to the application-defined callback function. This callback function can process the font information as desired. Enumeration continues until there are no more fonts or the callback function returns zero.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the EnumFontFamilies function.

int EnumFonts(

HDC  hdc,	// handle of device context
LPCTSTR  lpFaceName,	// address of font typeface name string
FONTENUMPROC  lpFontFunc,	// address of callback function
LPARAM  lParam	// address of application-supplied data
);
Parameters

hdc

Identifies the device context.

lpFaceName

Points to a null-terminated character string that specifies the typeface name of the desired fonts. If lpFaceName is NULL, EnumFonts randomly selects and enumerates one font of each available typeface.

lpFontFunc

Points to the application-defined callback function. For more information about the callback function, see the EnumFontsProc function.

lParam

Points to any application-defined data. The data is passed to the callback function along with the font information.

Return Value

If the function succeeds, the return value is the last value returned by the callback function. Its meaning is defined by the application.

Remarks

Use EnumFontFamilies instead of EnumFonts. The EnumFontFamilies function differs from the EnumFonts function in that it retrieves the style names associated with a TrueType font. With EnumFontFamilies, you can retrieve information about unusual font styles (for example, Outline) that cannot be enumerated using the EnumFonts function.

See Also

EnumFontFamilies, EnumFontsProc, GetDeviceCaps


EnumFontsProc

The EnumFontsProc function is an application-defined callback function that processes font data from the EnumFonts function.

int CALLBACK EnumFontsProc(

lplf  lplf,	// address of logical-font data
lptm  lptm,	// address of physical-font data
DWORD  dwType,	// font type
LPARAM  lpData	// address of application-defined data
);
Parameters

lplf

Points to a LOGFONT structure that contains information about the logical attributes of the font.

lptm

Points to a TEXTMETRIC structure that contains information about the physical attributes of the font.

dwType

Specifies the type of the font. This parameter can be a combination of the following values:

DEVICE_FONTTYPE
RASTER_FONTTYPE
TRUETYPE_FONTTYPE

lpData

Points to the application-defined data passed by EnumFonts.

Return Value

The return value must be a nonzero value to continue enumeration; to stop enumeration, it must be zero.

Remarks

The AND (&) operator can be used with the RASTER_FONTTYPE and DEVICE_FONTTYPE constants to determine the font type. The RASTER_FONTTYPE bit of the FontType parameter specifies whether the font is a raster or vector font. If the bit is one, the font is a raster font; if zero, it is a vector font. The DEVICE_FONTTYPE bit of FontType specifies whether the font is a device-based or graphics device interface (GDI)-based font. If the bit is one, the font is a device-based font; if zero, it is a GDI-based font.

If the device is capable of text transformations (scaling, italicizing, and so on) only the base font is enumerated. The user must inquire into the device's text-transformation abilities to determine which additional fonts are available directly from the device.

An application must register the EnumFontsProc function by passing its address to the EnumFonts function.

EnumFontsProc is a placeholder for the application-defined function name.

See Also

EnumFonts, LOGFONT, TEXTMETRIC


EnumForms

The EnumForms function enumerates the forms supported by the specified printer.

BOOL EnumForms(

HANDLE  hPrinter,	// handle of printer object
DWORD  Level,	// data-structure level
LPBYTE  pForm,	// points to buffer that receives form info. structure array
DWORD  cbBuf,	// count of bytes in buffer
LPDWORD  pcbNeeded,	// points to variable to receive count of bytes copied or required
LPDWORD  pcReturned	// points to variable to receive count of structures copied
);
Parameters

hPrinter

Identifies the printer for which the forms should be enumerated.

Level

Specifies the version of the structure to which pForm points. This value must be 1.

pForm

Points to a FORM_INFO_1 structure.

cbBuf

Specifies the size, in bytes, of the buffer to which pForm points.

pcbNeeded

Points to a variable that receives the number of bytes copied to or the number of bytes required for the array to which pForm points. If cbBuf is too small, this value specifies the number of bytes required; otherwise, this value specifies the number of bytes copied.

pcReturned

Points to a variable that receives the number of FORM_INFO_1 structures copied into the array to which pForm points.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The printer-object handle hPrinter is normally obtained by calling the OpenPrinter function. The AddPrinter function can also be used.

See Also

AddPrinter, FORM_INFO_1, OpenPrinter


EnumICMProfiles  (preliminaryWindows 95)
EnumICMProfiles  (preliminary−Windows 95)

The EnumICMProfiles function enumerates the different color profiles that the system supports for the specified device context.

int EnumICMProfiles(

HDC hdc,
ICMENUMPROC  lpICMEnumFunc,
LPARAM  lParam
);
Parameters

hdc

Handle to the device context.

lpICMEnumFunc

Pointer to the application-defined callback function. For more information, see the EnumICMProfilesProc function.

lParam

Application-supplied data. The data is passed to the callback function along with the color profile information.

Return Value

Returns −1 if there are no color profiles to enumerate or image color matching is not enabled. Otherwise, it returns the last value returned by the callback function, which may be zero if the callback interrupted the enumeration.

See Also

EnumICMProfilesProc


EnumICMProfilesProc  (preliminaryWindows 95)
EnumICMProfilesProc  (preliminary−Windows 95)

The EnumICMProfilesProc function is an application-defined callback function that processes color profile data from the EnumICMProfiles function.

int CALLBACK EnumICMProfilesProc(

LPTSTR lpszFilename,
LPARAM  lParam
);
Parameters

lpszFilename

Pointer to a null-terminated string specifying the name of the color profile file.

lParam

Application-supplied data passed by the EnumICMProfiles function.

Return Value

Returns a positive value to continue enumeration, or 0 to stop enumeration. The function must not return a negative value.

See Also

EnumICMProfiles


EnumJobs

The EnumJobs function initializes an array of either JOB_INFO_1 or JOB_INFO_2 structures with data describing the specified print jobs for the specified printer.

BOOL EnumJobs(

HANDLE  hPrinter,	// handle of printer object
DWORD  FirstJob,	// location of first job in print queue to enumerate
DWORD  NoJobs,	// number of jobs to enumerate
DWORD  Level,	// structure level
LPBYTE  pJob,	// address of structure array
DWORD  cbBuf,	// size of array, in bytes
LPDWORD  pcbNeeded,	// addr. of variable with no. of bytes copied (or required)
LPDWORD  pcReturned	// addr. of variable with no. of job info. structures copied
);
Parameters

hPrinter

Handle to the printer object whose print jobs the function will enumerate.

FirstJob

Specifies the one-based position within the print queue of the first print job to enumerate. For example, a value of 1 specifies that enumeration should begin at the first print job in the print queue; a value of 9 specifies that enumeration should begin at the ninth print job in the print queue.

NoJobs

Specifies the total number of print jobs to enumerate.

Level

Specifies whether the function should use JOB_INFO_1 or JOB_INFO_2 structures to store data for the enumerated jobs. A value of 1 specifies that the JOB_INFO_1 structure should be used; a value of 2 specifies that the JOB_INFO_2 structure should be used.

pJob

Points to an array of either JOB_INFO_1 or JOB_INFO_2 structures.

cbBuf

Specifies the size, in bytes, of the array pJob.

pcbNeeded

Points to a variable that receives the number of bytes copied if the function succeeds. If the function fails, the variable receives the number of bytes required.

pcReturned

Points to a variable that receives the number of JOB_INFO_1 or JOB_INFO_2 structures that were initialized.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The handle hPrinter is obtained by calling the OpenPrinter function.

The JOB_INFO_1 structure contains general print-job information; the JOB_INFO_2 structure has much more detailed information.

See Also

GetJob, JOB_INFO_1, JOB_INFO_2, OpenPrinter, SetJob


EnumLocalesProc

An EnumLocalesProc function is an application-defined callback function. It is called as a result of a call to the EnumSystemLocales function, and receives a pointer to a string buffer containing a locale identifier.

BOOL CALLBACK EnumLocalesProc(

LPTSTR  lpLocaleString	// pointer to locale identifier string
);
Parameters

lpLocaleString

Pointer to a string buffer containing a null-terminated locale identifier string. Note that lpLocaleString should be an LPWSTR for the Unicode (W) version of EnumLocalesProc, and an LPSTR for the ANSI (A) version of EnumLocalesProc.

Return Value

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

EnumLocalesProc is a placeholder for an application-defined function name.

An application registers an EnumLocalesProc function by passing its address to the EnumSystemLocales function.

A value of type LOCALE_ENUMPROC is a pointer to an EnumLocalesProc function.

See Also

EnumSystemLocales


EnumMetaFile

The EnumMetaFile function enumerates the records within a Windows-format metafile by retrieving each record and passing it to the specified callback function. The application-supplied callback function processes each record as required. The enumeration continues until the last record is processed or when the callback function returns zero.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the EnumEnhMetaFile function.

BOOL EnumMetaFile(

HDC  hdc,	// handle of device context
HMETAFILE  hmf,	// handle of Windows-format metafile
MFENUMPROC  lpMetaFunc,	// address of callback function
LPARAM  lParam	// address of callback function data
);
Parameters

hdc

Identifies a device context. This handle is passed to the callback function.

hmf

Identifies a Windows-format metafile.

lpMetaFunc

Points to an application-supplied callback function. For more information, see the EnumMetaFileProc callback function.

lParam

Points to optional callback-function data.

Return Value

If the callback function successfully enumerates all the records in the Windows-format metafile, the return value is TRUE; otherwise, it is FALSE.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced-format metafile functions.

To convert a Windows-format metafile into an enhanced-format metafile, use the SetWinMetaFileBits function.

You can use the EnumMetaFile function to embed one Windows-format metafile within another.

See Also

BeginPath, EnumEnhMetaFile, EnumMetaFileProc, PlayMetaFile, PlayMetaFileRecord, PolyBezier, SetWinMetaFileBits, SetWorldTransform


EnumMetaFileProc

The EnumMetaFileProc function is an application-defined callback function that processes Windows-format metafile records. This function is called by the EnumMetaFile function.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the EnhMetaFileProc and EnumEnhMetaFile functions.

int CALLBACK EnumMetaFileProc(

HDC  hDC,	// handle 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
);
Parameters

hDC

Identifies the device context passed to EnumMetaFile.

lpHTable

Points to a table of handles associated with the graphics objects (pens, brushes, and so on) in the metafile.

lpMFR

Points to one of the records in the metafile. This record should not be modified. (If modification is necessary, it should be performed on a copy of the record.)

nObj

Specifies the number of objects with associated handles in the handle table.

lpClientData

Points to any application-supplied data.

Return Value

This function must return a nonzero value to continue enumeration; to stop enumeration, it must return zero.

Remarks

An application must register the callback function by passing its address to the EnumMetaFile function.

EnumMetaFileProc is a placeholder for the application-supplied function name.

See Also

EnhMetaFileProc, EnumEnhMetaFile, EnumMetaFile


EnumMonitors

The EnumMonitors function initializes an array of MONITOR_INFO_1 structures with data describing the monitors for the specified server.

BOOL EnumMonitors(

LPTSTR  pName,	// address of server name
DWORD  Level,	// structure level
LPBYTE  pMonitors,	// address of structure array
DWORD  cbBuf,	// size, in bytes, of buffer
LPDWORD  pcbNeeded,	// addr. of variable with no. of bytes copied (or required)
LPDWORD  pcReturned	// addr. of variable with no. of job info. structures copied
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the monitors reside. If this parameter is NULL, the local monitors are enumerated.

Level

Specifies the version of the structure pointed to by pMonitors.

pMonitors

Points to an array of MONITOR_INFO_1 structures.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pMonitors.

pcbNeeded

Points to a variable that receives the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

pcReturned

Points to a variable that receives the number of MONITOR_INFO_1 structures that were returned in the buffer pointed to by pMonitors.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

MONITOR_INFO_1


EnumObjects

The EnumObjects function enumerates the pens or brushes available for the specified device context. This function calls the application-defined callback function once for each available object, supplying data describing that object. EnumObjects continues calling the callback function until the callback function returns zero or until all of the objects have been enumerated.

int EnumObjects(

HDC  hdc,	// handle of device context
int  nObjectType,	// object-type identifier
GOBJENUMPROC  lpObjectFunc,	// address of callback function
LPARAM  lParam	// address of application-supplied data
);
Parameters

hdc

Identifies the device context.

nObjectType

Specifies the object type. This parameter can be OBJ_BRUSH or OBJ_PEN.

lpObjectFunc

The address of the application-defined callback function. For more information about the callback function, see the EnumObjectsProc function.

lParam

Points to the application-defined data. The data is passed to the callback function along with the object information.

Return Value

The return value specifies the last value returned by the callback function. Its meaning is user-defined. The return value is -1 if there are too many objects to enumerate. In this case, the callback function is not called.

See Also

EnumObjectsProc, GetObject


EnumObjectsProc

The EnumObjectsProc function is an application-defined callback function that processes object data supplied by the EnumObjects function.

VOID CALLBACK EnumObjectsProc(

LPVOID  lpLogObject,	// address of graphic-object structure
LPARAM  lpData	// address of application-defined data
);
Parameters

lpLogObject

Points to a LOGPEN or LOGBRUSH structure describing the attributes of the object.

lpData

Points to the application-defined data passed by the EnumObjects function.

Return Value

This function does not return a value.

Remarks

An application must register this function by passing its address to the EnumObjects function. EnumObjectsProc is a placeholder for the application-defined function name.

See Also

EnumObjects, GlobalAlloc, GlobalLock, LOGPEN, LOGBRUSH


EnumPorts

The EnumPorts function enumerates the ports that are available for printing on a specified server.

BOOL EnumPorts(

LPTSTR  pName,	// pointer to server name
DWORD  Level,	// specifies type of port info structure
LPBYTE  pPorts,	// pointer to buffer to receive array of port info. structures
DWORD  cbBuf,	// specifies size, in bytes, of buffer
LPDWORD  pcbNeeded,	// pointer to number of bytes stored into buffer (or required  // buffer size)
LPDWORD  pcReturned	// pointer to number of PORT_INFO_*. structures stored into buffer
);
Parameters

pName

Pointer to a null-terminated string that specifies the name of the server whose printer ports you wish to enumerate.

If pName is NULL, the function enumerates the local machine's printer ports.

Level

Specifies the type of data structures pointed to by pPorts.

Windows 95: This value can be 1 or 2.

Windows NT: This value must be 1.

pPorts

Pointer to a buffer that receives an array of PORT_INFO_1 or PORT_INFO_2 structures. Each structure contains data that describes an available printer port. The value of Level specifies the type of structure. A Level value of 1 specifies PORT_INFO_1 structures. A Level value of 2 specifies PORT_INFO_2 structures.

Windows 95: The buffer can receive either type of data structure.

Windows NT: The buffer can receive only PORT_INFO_1 data structures.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pPorts.

pcbNeeded

Pointer to a variable that the function sets to the size, in bytes, of the data that enumerates the printer ports. If cbBuf is smaller than this value, EnumPorts fails, GetLastError returns ERROR_INSUFFICIENT_BUFFER, and the variable pointed to by pcbNeeded represents the required buffer size. If cbBuf is equal to or greater than this value, the variable pointed to by pcbNeeded represents the number of bytes stored into the buffer.

pcReturned

Pointer to a variable that the function sets to the number of PORT_INFO_* structures that it stores into the buffer pointed to by pPorts. This is the number of printer ports that are available on the specified server.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The EnumPorts function can succeed even if the server specified by pName does not have a printer defined.

See Also

AddPort, DeletePort, PORT_INFO_1


EnumPrinterDrivers

The EnumPrinterDrivers function enumerates all of the printer drivers installed on the specified printer server.

BOOL EnumPrinterDrivers(

LPTSTR  pName,	// pointer to server name
LPTSTR  pEnvironment,	// pointer to environment name
DWORD  Level,	// structure level
LPBYTE  pDriverInfo,	// pointer to an array of structures
DWORD  cbBuf,	// size, in bytes, of array
LPDWORD  pcbNeeded,	// pointer to number of bytes copied (or required)
LPDWORD  pcReturned	// pointer to number of DRIVER_INFO. structures
);
Parameters

pName

Pointer to a null-terminated string that specifies the name of the server on which the printer drivers should be enumerated.

If pName is NULL, the function enumerates the local machine's printer drivers.

pEnvironment

Pointer to a null-terminated string that specifies the environment. For example, "Windows NT x86" specifies Windows NT running on an Intel 80386 or 80486 processor. If this parameter is NULL, the function uses the current environment of the caller/client (not of the destination/server).

Level

Specifies the type of DRIVER_INFO_* structures pointed to by pDriverInfo. This value must be 1, 2, or 3.

Windows NT

The value must be 1 or 2.

pDriverInfo

Pointer to a buffer that receives an array of DRIVER_INFO_1, DRIVER_INFO_2, or DRIVER_INFO_3 structures. Each structure contains data that describes an available printer driver.

Windows NT

The structures must be either DRIVER_INFO_1 or DRIVER_INFO_2.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pDriverInfo.

pcbNeeded

Pointer to a value that the function sets to the size in bytes of the data that enumerates the printer drivers. If cbBuf is smaller than this value, EnumPrinterDrivers fails, and the variable pointed to by pcbNeeded represents the required buffer size. If cbBuf is equal to or greater than this value, the variable pointed to by pcbNeeded represents the number of bytes stored into the buffer.

pcReturned

Pointer to a value that specifies the number of DRIVER_INFO_* structures that it stores into the buffer pointed to by pDriverInfo. This is the number of printer drivers installed on the specified print server.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AddPrinterDriver, DRIVER_INFO_1, DRIVER_INFO_2, DRIVER_INFO_3, GetPrinterDriver


EnumPrinters

The EnumPrinters function enumerates available printers, print servers, domains, or print providers.

BOOL EnumPrinters(

DWORD  Flags,	// types of printer objects to enumerate
LPTSTR  Name,	// name of printer object
DWORD  Level,	// specifies type of printer info structure
LPBYTE  pPrinterEnum,	// pointer to buffer to receive printer info structures
DWORD  cbBuf,	// size, in bytes, of array
LPDWORD  pcbNeeded,	// addr. of variable with no. of bytes copied (or required)
LPDWORD  pcReturned	// addr. of variable with no. of printer info. structures copied
);
Parameters

Flags

Specifies the types of print objects that the function should enumerate. This value can be a combination of the following constants:

Value	Meaning
PRINTER_ENUM_CONNECTIONS	The function enumerates the list of printers to which the user has made previous connections.
PRINTER_ENUM_LOCAL	The function enumerates the locally installed printers.
PRINTER_ENUM_NAME	The function enumerates the printer identified by Name. This can be a server, a domain, or a print provider. If Name is NULL, the function enumerates available print providers.
PRINTER_ENUM_NETWORK	The function enumerates network printers known to the local server. This value is valid only if Level is 1.
PRINTER_ENUM_REMOTE	The function enumerates network printers. This value is valid only if Level is 1.
PRINTER_ENUM_SHARED	The function numerates printers that have the shared attribute.
If Level is 4, you can only use the PRINTER_ENUM_CONNECTIONS and PRINTER_ENUM_LOCAL constants.

Name

If Level is 1, Flags contains PRINTER_ENUM_NAME, and Name is non-NULL, Name points to a null-terminated string that specifies the name of the object to enumerate. This string can be the name of a server, a domain, or a print provider.

If Level is 1, Flags contains PRINTER_ENUM_NAME, and Name is NULL, the function enumerates the available print providers.

If Level is 1, Flags contains PRINTER_ENUM_REMOTE, and Name is NULL, the function enumerates the printers in the user's domain.

If Level is 2 or 5, Name points to a null-terminated string that specifies the name of a server whose printers are to be enumerated. If this string is NULL, the function enumerates the printers installed on the local machine.

If Level is 4, Name should be NULL. The function always queries on the local machine.

When Name is NULL, it enumerates printers that are installed on the local machine. These printers include those that are physically attached to the local machine as well as remote printers to which it has a network connection.

Level

Specifies the type of data structures pointed to by pPrinterEnum. Legal values are 1, 2, 4, and 5, which correspond to the PRINTER_INFO_1, PRINTER_INFO_2,  PRINTER_INFO_4, and PRINTER_INFO_5 data structures.

Windows 95: This value may be 1, 2, or 5.

Windows NT: This value may be 1, 2, or 4.

pPrinterEnum

Points to a buffer that receives an array of PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, or PRINTER_INFO_5 structures. Each structure contains data that describes an available print object. If Level is 1, the array contains PRINTER_INFO_1 structures. If Level is 2, the array contains PRINTER_INFO_2 structures. If Level is 4, the array contains PRINTER_INFO_4 structures. If Level is 5, the array contains PRINTER_INFO_5 structures.

Windows 95: The buffer cannot receive PRINTER_INFO_4 structures. It can receive any of the other types.

Windows NT: The buffer cannot receive PRINTER_INFO_5 structures. It can receive any of the other types.

cbBuf

Specifies the size, in bytes, of the array pointed to by pPrinterEnum.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

pcReturned

Points to a value that specifies the number of PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, or PRINTER_INFO_5 structures that the function returns in the array to which pPrinterEnum points.

Windows 95

The value must be 1, 2, or 5

Window NT

The value must be 1, 2, or 4.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If EnumPrinters returns a PRINTER_INFO_1 structure in which PRINTER_ENUM_CONTAINER is specified, this indicates that there is a hierarchy of printer objects. An application can enumerate the hierarchy by calling EnumPrinters again, setting Name to the value of the PRINTER_INFO_1 structure's pName member.

The EnumPrinters function does not retrieve security information. If PRINTER_INFO_2 structures are returned in the array pointed to by pPrinterEnum, their pSecurityDescriptor members will be set to NULL.

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

Windows NT: The PRINTER_INFO_4 structure provides an easy and extremely fast way to retrieve the names of the printers installed on a local machine, as well as the remote connections that a user has established. When EnumPrinters is called with a PRINTER_INFO_4 data structure, that function queries the registry for the specified information, then returns immediately. This differs from the behavior of EnumPrinters when called with other levels of PRINTER_INFO_* data structures. In particular, when EnumPrinters is called with a level 2 (PRINTER_INFO_2) data structure, it performs an OpenPrinter call on each remote connection. If a remote connection is down, or the remote server no longer exists, or the remote printer no longer exists, the function must wait for RPC to time out and consequently fail the OpenPrinter call. This can take a while. Passing a PRINTER_INFO_4 structure lets an application retrieve a bare minimium of required information; if more detailed information is desired, a subsequent EnumPrinter level 2 call can be made.

See Also

AddPrinter, DeletePrinter, GetPrinter, GetProfileString, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, PRINTER_INFO_5, SetPrinter


EnumPrintProcessorDatatypes

The EnumPrintProcessorDatatypes function enumerates the data types that a specifed print processor supports.

BOOL EnumPrintProcessorDatatypes(

LPTSTR  pName,	// points to server name string
LPTSTR  pPrintProcessorName,	// points to print processor name string
DWORD  Level,	// specifies version of print processor data type structures
LPBYTE  pDatatypes,	// points to buffer to receive print processor data type structures
DWORD   cbBuf,	// specifies size, in bytes, of buffer
LPDWORD  pcbNeeded,	// points to number of bytes copied (or required)
LPDWORD  pcReturned	// points to number of data structures obtained
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the print processor resides. If this parameter is NULL, the data types for the local print processor are enumerated.

pPrintProcessorName

Points to a null-terminated string that specifies the name of the print processor whose data types are to be enumerated.

Level

Specifies the version of the print-processor data type structures to be stored in the buffer pointed to by pDatatypes. This parameter must be 1.

pDatatypes

Points to an array of DATATYPES_INFO_1 structures. One structure is created for each available data type.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pDatatypes.

pcbNeeded

Points to a variable to receive the total size, in bytes, of the array of DATATYPES_INFO_1 structures.

If this value is less than or equal to cbBuf and the function succeeds, this is the number of bytes stored in the buffer pointed to by pDatatypes. If this number is greater than cbBuf, the buffer is too small, and you must call the function again with a buffer size at least as large as *pcbNeeded.

pcReturned

Points to a variable that the function sets to the number of data structures stored in the buffer pointed to by pDatatypes.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

DATATYPES_INFO_1, EnumPrintProcessors


EnumPrintProcessors

The EnumPrintProcessors function enumerates the print processors installed on the specified server.

BOOL EnumPrintProcessors(

LPTSTR  pName,	// points to server name
LPTSTR  pEnvironment,	// points to environment name
DWORD  Level,	// structure level
LPBYTE  pPrintProcessorInfo,	// points to structure array
DWORD  cbBuf,	// array length in bytes
LPDWORD  pcbNeeded,	// points to number of bytes copied (or required)
LPDWORD  pcReturned	// points to number of job info. structures copied
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the print processors reside. If this parameter is NULL, the local print processors are enumerated.

pEnvironment

Points to a null-terminated string that specifies the environment. For example, "Windows NT x86" specifies Windows NT running on an Intel 80386 or 80486 processor. If this parameter is NULL, the current environment of the calling application and client machine (not of the destination application and print server) is used.

Level

Specifies the version of the structure to which pPrintProcessorInfo points. This value must be 1.

pPrintProcessorInfo

Points to an array of PRINTPROCESSOR_INFO_1 structures. One structure is created for each available print processor.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pPrintProcessorInfo.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

pcReturned

Points to a value that specifies the number of PRINTPROCESSOR_INFO_1 structures that returned in the array to which pPrintProcessorInfo points.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AddPrintProcessor, EnumPrintProcessorDatatypes, PRINTPROCESSOR_INFO_1


EnumProps

The EnumProps function enumerates all entries in the property list of a window by passing them, one by one, to the specified callback function. EnumProps continues until the last entry is enumerated or the callback function returns FALSE.

int EnumProps(

HWND  hWnd,	// handle of window
PROPENUMPROC  lpEnumFunc	// address of callback function
);
Parameters

hWnd

Identifies the window whose property list is to be enumerated.

lpEnumFunc

Points to the callback function. For more information about the callback function, see the PropEnumProc function.

Return Value

The return value specifies the last value returned by the callback function. It is -1 if the function did not find a property for enumeration.

Remarks

An application can remove only those properties it has added. It must not remove properties added by other applications or by Windows itself.

See Also

EnumPropsEx, GetProp, PropEnumProc, RemoveProp, SetProp


EnumPropsEx

The EnumPropsEx function enumerates all entries in the property list of a window by passing them, one by one, to the specified callback function. EnumPropsEx continues until the last entry is enumerated or the callback function returns FALSE.

int EnumPropsEx(

HWND  hWnd,	// handle of window
PROPENUMPROCEX  lpEnumFunc,	// address of callback function
LPARAM  lParam	// application-defined data
);
Parameters

hWnd

Identifies the window whose property list is to be enumerated.

lpEnumFunc

Points to the callback function. For more information about the callback function, see the PropEnumProcEx function.

lParam

Contains application-defined data to be passed to the callback function.

Return Value

The return value specifies the last value returned by the callback function. It is -1 if the function did not find a property for enumeration.

Remarks

An application can remove only those properties it has added. It must not remove properties added by other applications or by Windows itself.

See Also

EnumProps, GetProp, PropEnumProcEx, RemoveProp, SetProp


EnumProtocols

The EnumProtocols function obtains information about a specified set of network protocols that are active on a local host.

INT EnumProtocols(

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

lpiProtocols

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

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

The following protocol identifier values are defined:

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

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

lpdwBufferLength

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

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

Return Value

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

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

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

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

SOCKET

OpenConnection (

    PTSTR ServiceName,

    PGUID ServiceType,

    BOOL Reliable,

    BOOL MessageOriented,

    BOOL StreamOriented,

    BOOL Connectionless,

    PINT ProtocolUsed

    )

{

    // local variables

    INT protocols[MAX_PROTOCOLS+1];

    BYTE buffer[2048];

    DWORD bytesRequired;

    INT err;

    PPROTOCOL_INFO protocolInfo;

    PCSADDR_INFO csaddrInfo;

    INT protocolCount;

    INT addressCount;

    INT i;

    DWORD protocolIndex;

    SOCKET s;

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

    //

    bytesRequired = sizeof(buffer);

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

    if ( err <= 0 )

        return INVALID_SOCKET;

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

    // support the desired characteristics.

    //

    protocolCount = err;

    protocolInfo = (PPROTOCOL_INFO)buffer;

    for ( i = 0, protocolIndex = 0;

        i < protocolCount && protocolIndex < MAX_PROTOCOLS;

        i++, protocolInfo++ ) {

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

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

        // oriented support implies fully reliable service.

        //

        if ( Reliable ) {

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

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

            // which the data arrives.

            //

            if ( (protocolInfo->dwServiceFlags &

                    XP_GUARANTEED_DELIVERY) == 0

                ||

                    (protocolInfo->dwServiceFlags &

                    XP_GUARANTEED_ORDER) == 0 ) {

                continue;

                }

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

            // characteristics requested.

            //

            if ( StreamOriented &&

                (protocolInfo->dwServiceFlags & XP_MESSAGE_ORIENTED)

                    != 0 &&

                (protocolInfo->dwServiceFlags & XP_PSEUDO_STREAM)

                     == 0 ) {

                continue;

                }

            if ( MessageOriented &&

                    (protocolInfo->dwServiceFlags & XP_MESSAGE_ORIENTED)

                              == 0 ) {

                continue;

                }

            }

        else if ( Connectionless ) {

            // Make sure that this is a connectionless protocol.

            //

            if ( (protocolInfo->dwServiceFlags & XP_CONNECTIONLESS)

                     != 0 )

                continue;

            }

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

        // protocols in which we're interested.

        //

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

        }

See Also

GetAddressByName, PROTOCOL_INFO


EnumRegisterWordProc  (preliminaryWindows 95)
EnumRegisterWordProc  (preliminary−Windows 95)

The EnumRegisterWordProc function is an application-defined callback function that process data of register string from the ImmEnumRegisterWord function.

UINT CALLBACK EnumRegisterWordProc(

LPCTSTR  lpReading,
DWORD  dwStyle,
LPCTSTR  lpszString,
LPVOID  lpData
);
Parameters

lpszReading

Pointer to a null-terminated string specifying the matched reading string.

dwStyle

Style of register string.

lpszString

Pointer to a null-terminated string specifying the matched register string.

lpData

Application-supplied data.

Return Value

Returns a nonzero value to continue enumeration; zero to stop enumeration.

See Also

ImmEnumRegisterWord


EnumResLangProc

The EnumResLangProc function is an application-defined callback function that receives resource languages as a result of a call to the EnumResourceLanguages function.

BOOL CALLBACK EnumResLangProc(

HANDLE  hModule,	// resource-module handle
LPCTSTR  lpszType,	// address of resource type
LPCTSTR  lpszName,	// address of resource name
WORD  wIDLanguage,	// resource language identifier
LONG  lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the languages are being enumerated. If this parameter is NULL, the function enumerates the resource languages in the module used to create the current process.

lpszType

Points to a null-terminated string specifying the type name of the resource for which the language is being enumerated. For standard resource types, this parameter should be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_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. For a list of the primary language identifiers and sublanguage identifiers that constitute a language identifier, see the MAKELANGID macro.

lParam

Specifies the application-defined parameter passed to the EnumResourceLanguages function. This parameter can be used in error checking.

Return Value

This callback function should return TRUE to continue enumeration; otherwise, it should return FALSE to stop enumeration.

Remarks

The EnumResLangProc function is a placeholder for the application-defined or library-defined function name.

See Also

EnumResourceLanguages, MAKELANGID


EnumResNameProc

The EnumResNameProc function is an application-defined callback function that receives resource names as a result of a call to the EnumResourceNames function.

BOOL CALLBACK EnumResNameProc(

HANDLE  hModule,	// resource-module handle
LPCTSTR  lpszType,	// address of resource type
LPTSTR  lpszName,	// address of resource name
LONG  lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the names are being enumerated. If this parameter is NULL, the function enumerates the resource names in the module used to create the current process.

lpszType

Points to a null-terminated string specifying the type name of the resource for which the name is being enumerated. For standard resource types, this parameter should be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_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.

Return Value

This callback function should return TRUE to continue enumeration; otherwise, it should return FALSE to stop enumeration.

Remarks

The EnumResNameProc function is a placeholder for the application-defined or library-defined function name.

See Also

EnumResourceNames


EnumResourceLanguages

The EnumResourceLanguages function searches a module for each resource of the specified type and name and passes the language of each resource it locates to a defined callback function.

BOOL EnumResourceLanguages(

HMODULE  hModule,	// resource-module handle
LPCTSTR  lpType,	// address of resource type
LPCTSTR  lpName,	// address of resource name
ENUMRESLANGPROC  lpEnumFunc,	// address of callback function
LONG  lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the languages are to be enumerated. If this parameter is NULL, the function enumerates the resource languages in the module used to create the current process.

lpType

Points to a null-terminated string specifying the type of the resource for which the language is being enumerated. For standard resource types, this parameter can be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_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
lpName

Points to a null-terminated string specifying the name of the resource for which the language is being enumerated.

lpEnumFunc

Points to the callback function to be called for each enumerated resource language. For more information, see the EnumResLangProc function.

lParam

Specifies an application-defined value passed to the callback function. This parameter may be used in error checking.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The EnumResourceLanguages function continues to enumerate resource languages until the callback function returns FALSE or all resource languages have been enumerated.

See Also

EnumResLangProc, EnumResourceNames, EnumResourceTypes


EnumResourceNames

The EnumResourceNames function searches a module for each resource of the specified type and passes the name of each resource it locates to an application-defined callback function.

BOOL EnumResourceNames(

HINSTANCE  hModule,	// resource-module handling
LPCTSTR  lpszType,	// address of resource type
ENUMRESNAMEPROC  lpEnumFunc,	// address of callback function
LONG  lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the names are to be enumerated. If this parameter is NULL, the function enumerates the resource names in the module used to create the current process.

lpszType

Points to a null-terminated string specifying the type name of the resource for which the name is being enumerated. For standard resource types, this parameter can be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_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 EnumResNameProc function.

lParam

Specifies an application-defined value passed to the callback function. This parameter can be used in error checking.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The EnumResourceNames function continues to enumerate resource names until the callback function returns FALSE or all resource names have been enumerated.

See Also

EnumResNameProc, EnumResourceLanguages, EnumResourceTypes


EnumResourceTypes

The EnumResourceTypes function searches a module for resources and passes each resource type it finds to an application-defined callback function.

BOOL EnumResourceTypes(

HMODULE  hModule,	// resource-module handle
ENUMRESTYPEPROC  lpEnumFunc,	// address of callback function
LONG  lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the types are to be enumerated. If this parameter is NULL, the function enumerates the resource types in the module used to create the current process.

lpEnumFunc

Points to the callback function to be called for each enumerated resource type. For more information, see the EnumResTypeProc function.

lParam

Specifies an application-defined value passed to the callback function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The EnumResourceTypes function continues to enumerate resource types until the callback function returns FALSE or all resource types have been enumerated.

See Also

EnumResourceLanguages, EnumResourceNames, EnumResTypeProc


EnumResTypeProc

The EnumResTypeProc function is an application-defined callback function that receives resource types as a result of a call to the EnumResourceTypes function.

BOOL CALLBACK EnumResTypeProc(

HANDLE  hModule,	// resource-module handle
LPTSTR  lpszType,	// address of resource type
LONG  lParam	// application-defined parameter
);
Parameters

hModule

Identifies the module whose executable file contains the resources for which the types are to be enumerated. If this parameter is NULL, the function enumerates the resource types in the module used to create the current process.

lpszType

Points to a null-terminated string specifying the type name of the resource for which the type is being enumerated. For standard resource types, this parameter can be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_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.

Return Value

The callback function should return TRUE to continue enumeration; otherwise, it should return FALSE to stop enumeration.

Remarks

The EnumResTypeProc function is a placeholder for the application-defined or library-defined function name.

See Also

EnumResourceTypes


EnumServicesStatus

The EnumServicesStatus function enumerates services in the specified service control manager database. The name and status of each service are provided.

BOOL EnumServicesStatus(

SC_HANDLE  hSCManager,	// handle of service control manager database
DWORD  dwServiceType,	// type of services to enumerate
DWORD  dwServiceState,	// state of services to enumerate
LPENUM_SERVICE_STATUS  lpServices,	// address of service status buffer
DWORD  cbBufSize,	// size of service status buffer
LPDWORD  pcbBytesNeeded,	// address of variable for bytes needed
LPDWORD  lpServicesReturned,	// address of variable for number returned
LPDWORD  lpResumeHandle	// address of variable for next entry
);
Parameters

hSCManager

Identifies the service control manager database. The OpenSCManager function returns this handle which must have SC_MANAGER_ENUMERATE_SERVICE access.

dwServiceType

Specifies the type of services to enumerate. It must be one or both of the following values:

Value	Meaning
SERVICE_WIN32	Enumerates services of type SERVICE_WIN32_OWN_PROCESS and SERVICE_WIN32_SHARE_PROCESS.
SERVICE_DRIVER	Enumerates services of type SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER.
dwServiceState

Specifies the services to enumerate based on their running state. It must be one or both of the following values:

Value	Meaning
SERVICE_ACTIVE	Enumerates services that are in the following states: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, and SERVICE_PAUSED.
SERVICE_INACTIVE	Enumerates services that are in the SERVICE_STOPPED state.
lpServices

Points to an array of ENUM_SERVICE_STATUS structures in which the name and service status information for each service in the database is returned.

cbBufSize

Specifies the size, in bytes, of the buffer pointed to by the lpServices parameter.

pcbBytesNeeded

Points to a variable that receives the number of bytes needed to return the remaining service entries.

lpServicesReturned

Points to a variable that receives the number of service entries returned.

lpResumeHandle

Points to a 32-bit variable that, on input, specifies the starting point of enumeration. The first time this function is called, the variable's value is set to zero. On output, the variable's value is zero if the function succeeds. If the function returns FALSE and the GetLastError function returns ERROR_MORE_DATA, the variable's value is used to indicate the next unread service entry when the function is called again to retrieve the additional data.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with SC_MANAGER_ENUMERATE_SERVICE access.
ERROR_INVALID_HANDLE
	The specified handle is invalid.
ERROR_INVALID_PARAMETER
	A parameter that was specified is invalid.
ERROR_MORE_DATA
	There are more service entries than would fit into the lpServices buffer. The actual number of service entries written to lpServices is returned in the lpServicesReturned parameter. The number of bytes required to get the remaining entries is returned in the pcbBytesNeeded parameter. The remaining services can be enumerated by additional calls to EnumServicesStatus with the lpResumeHandle parameter indicating the next service to read.
See Also

EnumDependentServices, ENUM_SERVICE_STATUS, OpenSCManager


EnumSystemCodePages

The EnumSystemCodePages function enumerates the code pages that are either installed on or supported by a system. The dwFlags parameter determines whether the function enumerates installed or supported code pages. The function enumerates the code pages by passing code page identifiers, one at a time, to the specified application-defined callback function. This continues until all of the installed or supported code page identifiers have been passed to the callback function, or the callback function returns FALSE.

BOOL EnumSystemCodePages(

CODEPAGE_ENUMPROC  lpCodePageEnumProc,	// pointer to enumeration callback function
DWORD  dwFlags	// indicates which code pages to enumerate
);
Parameters

lpCodePageEnumProc

Points to an application-defined callback function. The EnumSystemCodePages function enumerates code pages by making repeated calls to this callback function. For more information, see the EnumCodePagesProc callback function.

dwFlags

Specifies the code pages to enumerate. This parameter can be one of the following values:

Value	Meaning
CP_INSTALLED	Enumerate only installed code pages.
CP_SUPPORTED	Enumerate all supported code pages.
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_PARAMETER
ERROR_BADDB
ERROR_INVALID FLAGS

Remarks

The CP_INSTALLED and CP_SUPPORTED flags are mutually exclusive.

See Also

EnumCodePagesProc


EnumSystemLocales

The EnumSystemLocales function enumerates the locales that are either installed on or supported by a system. The dwFlags parameter determines whether the function enumerates installed or supported system locales. The function enumerates locales by passing locale identifiers, one at a time, to the specified application-defined callback function. This continues until all of the installed or supported locale identifiers have been passed to the callback function or the callback function returns FALSE.

BOOL EnumSystemLocales(

LOCALE_ENUMPROC  lpLocaleEnumProc,	// pointer to enumeration callback function
DWORD  dwFlags	// indicates which locales to enumerate
);
Parameters

lpLocaleEnumProc

Points to an application-defined callback function. The EnumSystemLocales function enumerates locales by making repeated calls to this callback function. For more information, see the EnumLocalesProc callback function.

dwFlags

Specifies the locale identifiers to enumerate. This parameter can be one of the following values:

Value	Meaning
LCID_INSTALLED	Enumerate only installed locale identifiers.
LCID_SUPPORTED	Enumerate all supported locale identifiers.
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_PARAMETER
ERROR_BADDB
ERROR_INVALID FLAGS

Remarks

The LCID_INSTALLED and LCID_SUPPORTED flags are mutually exclusive.

See Also

EnumLocalesProc


EnumTaskWindows

The EnumTaskWindows function is now obsolete. It has been superseded by the EnumThreadWindows function.

To maintain compatibility for 16-bit applications, EnumTaskWindows has been replaced with a macro that calls EnumThreadWindows. Earlier applications can continue to call EnumTaskWindows as previously documented, but new applications should use EnumThreadWindows.


EnumThreadWindows

The EnumThreadWindows function enumerates all 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. This function supersedes the EnumTaskWindows function.

BOOL EnumThreadWindows(

DWORD  dwThreadId,	// thread identifier
WNDENUMPROC  lpfn,	// address of callback function
LPARAM  lParam	// application-defined value
);
Parameters

dwThreadId

Identifies the thread whose windows are to be enumerated.

lpfn

Points to an application-defined callback function. For more information about the callback function, see the EnumThreadWndProc callback function.

lParam

Specifies a 32-bit, application-defined value to be passed to the callback function.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

EnumChildWindows, EnumThreadWndProc, EnumWindows


EnumThreadWndProc

The EnumThreadWndProc function is an application-defined callback function that receives the window handles associated with a thread as a result of a call to the EnumThreadWindows function.

BOOL CALLBACK EnumThreadWndProc(

HWND  hwnd,	// handle of window
LPARAM  lParam	// application-defined value
);
Parameters

hwnd

Identifies a window associated with the thread specified in the EnumThreadWindows function.

lParam

Specifies the application-defined value given in the EnumThreadWindows function.

Return Value

To continue enumeration, the callback function must return TRUE; to stop enumeration, it must return FALSE.

Remarks

The callback function can perform any desired task.

An application must register this callback function by passing its address to the EnumThreadWindows function. EnumThreadWndProc is a placeholder for the application-defined function name.

See Also

EnumThreadWindows


EnumTimeFormats

The EnumTimeFormats function enumerates the time formats that are available for a specified locale. The function enumerates the time formats by passing a pointer to a string buffer containing a time format to an application-defined callback function. It continues to do so until the last time format is found or the callback function returns FALSE.

BOOL EnumTimeFormats(

TIMEFMT_ENUMPROC  lpTimeFmtEnumProc,	// pointer to enumeration callback function
LCID  Locale,	// locale whose time formats are of interest
DWORD  dwFlags	// currently unused
);
Parameters

lpTimeFmtEnumProc

Points to an application-defined callback function. See the EnumTimeFormatsProc callback function for further details.

Locale

Specifies the locale to retrieve time format information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

Currently unused. Must be zero.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_PARAMETER
ERROR_BADDB
ERROR_INVALID FLAGS

See Also

EnumTimeFormatsProc, EnumCalendarInfo, EnumDateFormats


EnumTimeFormatsProc

An EnumTimeFormatsProc function is an application-defined callback function. It is called as a result of a call to the EnumTimeFormats function, and receives a pointer to a string buffer containing a time format string.

BOOL CALLBACK EnumTimeFormatsProc(

LPTSTR  lpTimeFormatString	// pointer to time format string
);
Parameters

lpTimeFormatString

Pointer to a string buffer containing a null-terminated time format string. Note that lpTimeFormatString should be an LPWSTR for the Unicode (W) version of EnumTimeFormatsProc, and an LPSTR for the ANSI (A) version of EnumTimeFormatsProc.

Return Value

To continue enumeration, the callback function should return TRUE.

To stop enumeration, the callback function should return FALSE.

Remarks

EnumTimeFormatsProc is a placeholder for an application-defined function name.

An EnumTimeFormatsProc function can carry out any task

An application registers an EnumTimeFormatsProc function by passing its address to the EnumTimeFormats function.

A value of type TIMEFMT_ENUMPROC is a pointer to an EnumTimeFormatsProc function.

See Also

EnumTimeFormats


EnumWindows

The EnumWindows function enumerates all top-level windows on the screen by passing the handle of each window, in turn, to an application-defined callback function. EnumWindows continues until the last top-level window is enumerated or the callback function returns FALSE.

BOOL EnumWindows(

WNDENUMPROC  lpEnumFunc,	// address of callback function
LPARAM  lParam	// application-defined value
);
Parameters

lpEnumFunc

Points to an application-defined callback function. For more information, see the EnumWindowsProc callback function.

lParam

Specifies a 32-bit, application-defined value to be passed to the callback function.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The EnumWindows function does not enumerate child windows.

This function is more reliable than calling the GetWindow function in a loop. An application that calls GetWindow to perform this task risks being caught in an infinite loop or referencing a handle of a window that has been destroyed.

See Also

EnumChildWindows, EnumWindowsProc, GetWindow


EnumWindowsProc

The EnumWindowsProc function is an application-defined callback function that receives top-level window handles as a result of a call to the EnumWindows function.

BOOL CALLBACK EnumWindowsProc(

HWND  hwnd,	// handle of parent window
LPARAM  lParam	// application-defined value
);
Parameters

hwnd

Identifies a top-level window.

lParam

Specifies the application-defined value given in EnumWindows.

Return Value

To continue enumeration, the callback function must return TRUE; to stop enumeration, it must return FALSE.

Remarks

The callback function can perform any desired task.

An application must register this callback function by passing its address to EnumWindows. EnumWindowsProc is a placeholder for the application-defined function name.

See Also

EnumWindows


EnumWindowStationProc  (preliminaryWindows NT)
EnumWindowStationProc  (preliminary−Windows NT)

The EnumWindowStationProc function is an application-defined callback function that receives a window station name as a result of a call to the EnumWindowStations function.

BOOL EnumWindowStationProc(

LPTSTR lpszWindowStation	// name of a window station
LPARAM lParam	// value specified in EnumWindowStations call
);
Parameters

lpszWindowStation

Points to the null-terminated name of a window station.

lParam

Specifies the application-defined value given in the EnumWindowStations function.

Return Value

To continue enumeration, the callback function must return TRUE. To stop enumeration, it must return FALSE.

See Also

EnumWindowStations


EnumWindowStations  (preliminaryWindows NT)
EnumWindowStations  (preliminary−Windows NT)

The EnumWindowStations function enumerates all windowstations in the system by passing the name of each window station, in turn, to an application-defined callback function.

BOOL EnumWindowStations(

WINSTAENUMPROC lpEnumFunc,	// points to application's callback function
LPARAM lParam	// 32-bit value to pass to the callback function
);
Parameters

lpEnumFunc

Points to an application-defined EnumWindowStationProc callback function.

lParam

Specifies a 32-bit application-defined value to be passed to the callback function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The EnumWindowStations function enumerates only those window stations for which the calling process has WINSTA_ENUMERATE access.

EnumWindowStations repeatedly invokes the lpEnumFunc callback function until the last window station is enumerated or the callback function returns FALSE.

See Also

EnumWindowStationProc


EqualPrefixSid

The EqualPrefixSid function tests two security-identifier (SID) prefix values for equality. An SID prefix is the entire SID except for the last subauthority value.

BOOL EqualPrefixSid(

PSID  pSid1,	// address of first SID to compare
PSID  pSid2	// address of second SID to compare
);
Parameters

pSid1

Points to the first SID structure to compare. This structure is assumed to be valid.

pSid2

Points to the second SID structure to compare. It also is assumed to be valid.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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


EqualRect

The EqualRect function determines whether the two specified rectangles are equal by comparing the coordinates of their upper-left and lower-right corners.

BOOL EqualRect(

CONST RECT  *lprc1,	// address of structure with first rectangle
CONST RECT  *lprc2	// address of structure with second rectangle
);
Parameters

lprc1

Points to a RECT structure that contains the logical coordinates of the first rectangle.

lprc2

Points to a RECT structure that contains the logical coordinates of the second rectangle.

Return Value

If the two rectangles are identical, the return value is TRUE; otherwise, it is FALSE. To get extended error information, call GetLastError.

See Also

IsRectEmpty, PtInRect, RECT


EqualRgn

The EqualRgn function checks the two specified regions to determine whether they are identical. The function considers two regions identical if they are equal in size and shape.

BOOL EqualRgn(

HRGN  hSrcRgn1,	// handle of first region
HRGN  hSrcRgn2	// handle of second region
);
Parameters

hSrcRgn1

Identifies a region.

hSrcRgn2

Identifies a region.

Return Value

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


EqualSid

The EqualSid function tests two security identifier (SID) values for equality. Two SIDs must match exactly to be considered equal.

BOOL EqualSid(

PSID  pSid1,	// address of first SID to compare
PSID  pSid2	// address of second SID to compare
);
Parameters

pSid1

Points to the first SID structure to compare. This structure is assumed to be valid.

pSid2

Points to the second SID structure to compare. It also is assumed to be valid.

Return Value

If the SID structures are equal, the return value is TRUE; otherwise, it is FALSE. To get extended error information, call GetLastError.

If either SID structure is invalid, the return value is undefined.

See Also

EqualPrefixSid, IsValidSid, SID


EraseTape

The EraseTape function erases all or part of a tape.

DWORD EraseTape(

HANDLE  hDevice,	// handle of open device
DWORD  dwEraseType,	// type of erasure to perform
BOOL  bImmediate	// return after erase operation begins
);
Parameters

hDevice

Identifies the device where the tape is to be erased. This handle is created by using the CreateFile function.

dwEraseType

Specifies the erasing technique. This parameter can be one of the following values:

Value	Description
TAPE_ERASE_LONG	Erases the tape from the current position to the end of the current partition.
TAPE_ERASE_SHORT	Writes an erase gap or end-of-data marker at the current position.
bImmediate

Specifies whether to return as soon as the erase operation begins. If this parameter is TRUE, the function returns immediately; if it is FALSE, the function does not return until the erase operation has been completed.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes:

Error code	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

Some tape devices do not support certain tape operations. To determine your tape device's capabilities, see your tape device documentation and use the GetTapeParameters function.

See Also

CreateFile, GetTapeParameters


Escape

The Escape function allows applications to access capabilities of a particular device not directly available through GDI. Escape calls made by an application are translated and sent to the driver.

int Escape(

HDC  hdc,	// handle of device context
int  nEscape,	// escape function
int  cbInput,	// number of bytes in input structure
LPCSTR  lpvInData,	// address of input structure
LPVOID  lpvOutData	// address of output structure
);
Parameters

hdc

Identifies the device context.

nEscape

Specifies the escape function to be performed. This parameter must be one of the predefined escape values. Use the ExtEscape function if your application defines a private escape value.

cbInput

Specifies the number of bytes of data pointed to by the lpvInData parameter.

lpvInData

Points to the input structure required for the specified escape.

lpvOutData

Points to the structure that receives output from this escape. This parameter should be NULL if no data is returned.

Return Value

If the function succeeds, the return value is greater than zero, except with the QUERYESCSUPPORT printer escape, which checks for implementation only. If the escape is not implemented, the return value is zero.

If the function fails, the return value is an error. To get extended error information, call GetLastError.

Errors

If the function fails, the return value is one of the following values.

Value	Meaning
SP_ERROR	General error. If SP_ERROR is returned, Escape may set the last error value to: ERROR_INVALID_PARAMETER ERROR_DISK_FULL ERROR_NOT_ENOUGH_MEMORY ERROR_PRINT_CANCELLED
SP_OUTOFDISK	Not enough disk space is currently available for spooling, and no more space will become available.
SP_OUTOFMEMORY	Not enough memory is available for spooling.
SP_USERABORT	The user terminated the job through Windows Print Manager.
Remarks

The Win32 API provides six new functions that supersede some printer escapes:

Function	Description
AbortDoc	Terminates a print job. Supersedes the ABORTDOC escape.
EndDoc	Ends a print job. Supersedes the ENDDOC escape.
EndPage	Ends a page. Supersedes the NEWFRAME escape. Unlike NEWFRAME, this function is always called after printing a page.
SetAbortProc	Sets the abort function for a print job. Supersedes the SETABORTPROC escape.
StartDoc	Starts a print job. Supersedes the STARTDOC escape.
StartPage	Prepares printer driver to receive data.
The Win32 API provides six new indexes for the GetDeviceCaps function that supersede some printer escapes:

Index	Description
PHYSICALWIDTH	Width, in pixels, of the physical page. (Supersedes the GETPHYSPAGESIZE escape.)
PHYSICALHEIGHT	Height, in pixels, of the physical page. (Supersedes the GETPHYSPAGESIZE escape.)
PHYSICALOFFSETX	Offset in the x direction, in pixels, from the upper-left corner of the physical page where the actual printing or drawing begins. (Supersedes the GETPRINTINGOFFSET escape.)
PHYSICALOFFSETY	Offset in the y direction, in pixels, from the upper-left corner of the physical page where the actual printing or drawing begins. (Supersedes the GETPRINTINGOFFSET escape.)
SCALINGFACTORX	Scaling factor for the x-axis of a printer. (Supersedes the GETSCALINGFACTOR escape.)
SCALINGFACTORY	Scaling factor for the y-axis of a printer. (Supersedes the GETSCALINGFACTOR escape.)
Of the original printer escapes, only the following can be used by Win32-based application:

Escape	Description
QUERYYESCSUPPORT	Determines whether a particular escape is implemented by the device driver.
Following is a list of the obsolete printer escapes that are supported only for compatibility with 16-bit versions of Windows:

Escape	Description
ABORTDOC	Stops the current print job and erases everything the application has written to the device since the last ENDDOC escape.
ENDDOC	Ends a print job started by the STARTDOC escape.
GETPHYSPAGESIZE	Retrieves the physical page size and copies it to the specified location.
GETPRINTINGOFFSET	Retrieves the offset from the upper-left corner of the physical page where the actual printing or drawing begins.
GETSCALINGFACTOR	Retrieves the scaling factors for the x-axis and the y-axis of a printer.
NEWFRAME	Informs the printer that the application has finished writing to a page.
NEXTBAND	Informs the printer that the application has finished writing to a band.
PASSTHROUGH	Allows the application to send data directly to a printer.
SETABORTPROC	Sets the Abort function for a print job.
STARTDOC	Informs a printer driver that a new print job is starting.
See Also

AbortDoc, EndDoc, EndPage, ExtEscape, SetAbortProc, StartDoc, StartPage, ResetDC,


EscapeCommFunction

The EscapeCommFunction function directs a specified communications device to perform an extended function.

BOOL EscapeCommFunction(

HANDLE  hFile,	// handle of communications device
DWORD  dwFunc	// extended function to perform
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

dwFunc

Specifies the code of the extended function to perform. This parameter can be one of the following values:

Value	Meaning
CLRDTR	Clears the DTR (data-terminal-ready) signal.
CLRRTS	Clears the RTS (request-to-send) signal.
SETDTR	Sends the DTR (data-terminal-ready) signal.
SETRTS	Sends the RTS (request-to-send) signal.
SETXOFF	Causes transmission to act as if an XOFF character has been received.
SETXON	Causes transmission to act as if an XON character has been received.
SETBREAK	Suspends character transmission and places the transmission line in a break state until the ClearCommBreak function is called (or EscapeCommFunction is called with the CLRBREAK extended function code). The SETBREAK extended function code is identical to the SetCommBreak function. Note that this extended function does not flush data that has not been transmitted.
CLRBREAK	Restores character transmission and places the transmission line in a nonbreak state. The CLRBREAK extended function code is identical to the ClearCommBreak function.
Return Value

If the function succeeds, the return value is TRUE.

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

See Also

ClearCommBreak, CreateFile, EscapeCommFunction, SetCommBreak


ExcludeClipRect

The ExcludeClipRect function creates a new clipping region that consists of the existing clipping region minus the specified rectangle.

int ExcludeClipRect(

HDC  hdc,	// handle of device context
int  nLeftRect,	// x-coordinate of upper-left corner of rectangle
int  nTopRect,	// y-coordinate of upper-left corner of rectangle
int  nRightRect,	// x-coordinate of lower-right corner of rectangle
int  nBottomRect	// y-coordinate of lower-right corner of rectangle
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the logical x-coordinate of the upper-left corner of the rectangle.

nTopRect

Specifies the logical y-coordinate of the upper-left corner of the rectangle.

nRightRect

Specifies the logical x-coordinate of the lower-right corner of the rectangle.

nBottomRect

Specifies the logical y-coordinate of the lower-right corner of the rectangle.

Return Value

If the function succeeds, the return value specifies the new clipping region's complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	No region was created.
Remarks

The lower and right edges of the given rectangle are not excluded from the clipping region.

See Also

IntersectClipRect


ExcludeUpdateRgn

The ExcludeUpdateRgn function prevents drawing within invalid areas of a window by excluding an updated region in the window from a clipping region.

int ExcludeUpdateRgn(

HDC  hDC,	// handle of device context
HWND  hWnd	// handle of window
);
Parameters

hDC

Identifies the device context associated with the clipping region.

hWnd

Identifies the window to update.

Return Value

The return value specifies the complexity of the excluded region; it can be any one of the following values:

Value	Meaning
COMPLEXREGION	Region consists of more than one rectangle.
ERROR	An error occurred.
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
See Also

BeginPaint, GetUpdateRect, GetUpdateRgn, UpdateWindow


ExitProcess

The ExitProcess function ends a process and all its threads.

VOID ExitProcess(

UINT  uExitCode	// exit code for all threads
);
Parameters

uExitCode

Specifies the exit code for the process, and for all threads that are terminated as a result of this call. Use the GetExitCodeProcess function to retrieve the process's exit value. Use the GetExitCodeThread function to retrieve a thread's exit value.

Return Value

This function does not return a value.

Remarks

ExitProcess is the preferred method of ending a process. This function provides a clean process shutdown. This includes calling the entry-point function of all attached dynamic-link libraries (DLLs) with a value indicating that the process is detaching from the DLL. If a process terminates by calling TerminateProcess, the DLLs that the process is attached to are not notified of the process termination.

After all attached DLLs have executed any process termination value, this function terminates the current process.

Terminating a process causes the following:

1.	All of the object handles opened by the process are closed.

2.	All of the threads in the process terminate their execution.

3.	The state of the process object becomes signaled, satisfying any threads that had been waiting for the process to terminate.

4.	The states of all threads of the process become signaled, satisfying any threads that had been waiting for the threads to terminate.

5.	The termination status of the process changes from STILL_ACTIVE to the exit value of the process.

Terminating a process does not cause child processes to be terminated.

Terminating a process does not necessarily remove the process object from the operating system. A process object is deleted when the last handle to the process is closed.

The ExitProcess, ExitThread, CreateThread, CreateRemoteThread functions, and a process that is starting (as the result of a call by CreateProcess) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	ExitProcess does not return until no threads are in their DLL initialization or detach routines.

See Also

CreateProcess, CreateRemoteThread, CreateThread, ExitThread, GetExitCodeProcess, GetExitCodeThread, OpenProcess, TerminateProcess


ExitThread

The ExitThread function ends a thread.

VOID ExitThread(

DWORD  dwExitCode	// exit code for this thread
);
Parameters

dwExitCode

Specifies the exit code for the calling thread. Use the GetExitCodeThread function to retrieve a thread's exit code.

Return Value

This function does not return a value.

Remarks

ExitThread is the preferred method of exiting a thread. When this function is called (either explicitly or by returning from a thread procedure), the current thread's stack is deallocated and the thread terminates. The entry-point function of all attached dynamic-link libraries (DLLs) is invoked with a value indicating that the thread is detaching from the DLL.

If the thread is the last thread in the process when this function is called, the thread's process is also terminated.

The state of the thread object becomes signaled, releasing any other threads that had been waiting for the thread to terminate. The thread's termination status changes from STILL_ACTIVE to the value of the dwExitCode parameter.

Terminating a thread does not necessarily remove the thread object from the operating system. A thread object is deleted when the last handle to the thread is closed.

The ExitProcess, ExitThread, CreateThread, CreateRemoteThread functions, and a process that is starting (as the result of a CreateProcess call) are serialized between each other within a process. Only one of these events can happen in an address space at a time. This means the following restrictions hold:

•	During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.

•	Only one thread in a process can be in a DLL initialization or detach routine at a time.

•	ExitProcess does not return until no threads are in their DLL initialization or detach routines.

A thread that uses functions from the C run-time libraries should use the _beginthread and _endthread C run-time functions for thread management rather than CreateThread and ExitThread. Failure to do so results in small memory leaks when ExitThread is called.

See Also

CreateProcess, CreateRemoteThread, CreateThread, ExitProcess, FreeLibraryAndExitThread, GetExitCodeThread, TerminateThread


ExitWindows

The ExitWindows function logs the current user off.

BOOL ExitWindows(

DWORD  dwReserved,	// reserved
UINT  uReserved	// reserved
);
Parameters

dwReserved

Reserved; must be zero.

uReserved

Reserved; must be zero.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Windows NT: The ExitWindows function asks applications if they want to terminate by sending the WM_QUERYENDSESSION message to the main window of all running applications.

Windows 95: The ExitWindows function sends the WM_QUERYENDSESSION message to all applications except the one that called ExitWindows.

An application agrees to terminate by returning TRUE when it receives this message (or by allowing the DefWindowProc function to process the message). If any application returns FALSE when it receives the WM_QUERYENDSESSION message, the shutdown is canceled.

After Windows processes the results of the WM_QUERYENDSESSION message, it sends the WM_ENDSESSION message with the wParam parameter set to TRUE if the system is shutting down and to FALSE if it is not.

Windows does not allow new applications to start up during the shutdown process.

See Also

DefWindowProc, ExitWindowsEx


ExitWindowsEx

The ExitWindowsEx function either logs off, shuts down, or shuts down and restarts the system.

BOOL ExitWindowsEx(

UINT  uFlags,	// shutdown operation
DWORD  dwReserved	// reserved
);
Parameters

uFlags

Specifies the type of shutdown. This parameter must be some combination of the following values:

Value	Meaning
EWX_FORCE	Forces processes to terminate. Instead of bringing up the "application not responding" dialog box for the user, this value 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. Then it logs the user off.
EWX_POWEROFF	Shuts down the system and turns off the power. The application must have the SE_SHUTDOWN_NAME privilege (for more information, see the Remarks section) and the system must support the power-off feature.
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 Remarks 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 Remarks section).
dwReserved

Reserved; this parameter is ignored.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

To shut down or restart the system, the calling process must use the AdjustTokenPrivileges function to enable the SE_SHUTDOWN_NAME privilege.

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 value is specified, Windows always forces applications to close and does not display the dialog box.

The ExitWindowsEx function sends a separate notification message, CTRL_SHUTDOWN_EVENT or CTRL_LOGOFF_EVENT as the situation warrants, to console processes. A console process routes these messages to its HandlerRoutine functions, which are added and removed by calls to the SetConsoleCtrlHandler function. ExitWindowsEx sends these notification messages asynchronously; thus, an application cannot assume that the console notification messages have been handled when a call to ExitWindowsEx returns.

See Also

AdjustTokenPrivileges, ExitWindows, HandlerRoutine, SetConsoleCtrlHandler


ExpandEnvironmentStrings

The ExpandEnvironmentStrings function expands environment-variable strings and replaces them with their defined values.

DWORD ExpandEnvironmentStrings(

LPCTSTR  lpSrc,	// address of string with environment variables
LPTSTR  lpDst,	// address of string with expanded environment variables
DWORD  nSize	// maximum characters in expanded string
);
Parameters

lpSrc

Points to a null-terminated string that might contain references to environment-variable strings of the form:

%variableName%

For each such reference, the %variableName% portion is replaced with the current value of that environment variable.

The replacement rules are the same as those used by the command interpreter. Case is ignored when looking up the environment-variable name. If the name is not found, the %variableName% portion is left undisturbed.

lpDst

Points to a buffer to receive a copy of the source buffer, after all environment-variable name substitutions have been performed.

nSize

Specifies the maximum number of characters that can be stored in the buffer pointed to by the lpDst parameter, including the terminating null character.

Return Value

If the function succeeds, the return value is the number of characters stored in the destination buffer. If the number of characters is greater than the size of the destination buffer, the return value is the size of the buffer required to hold the expanded strings.

If the function fails, the return value is zero. To get extended error information, call GetLastError.


ExtCreatePen

The ExtCreatePen function creates a logical cosmetic or geometric pen that has the specified style, width, and brush attributes.

HPEN ExtCreatePen(

DWORD  dwPenStyle,	// pen style
DWORD  dwWidth,	// pen width
CONST LOGBRUSH *  lplb,	// address of structure for brush attributes
DWORD  dwStyleCount,	// length of array containing custom style bits
CONST DWORD *  lpStyle	// optional array of custom style bits
);
Parameters

dwPenStyle

Specifies a combination of type, style, end cap, and join attributes. The values from each category are combined by using the bitwise OR operator (|).

The pen type can be one of the following values:

Type	Description
PS_GEOMETRIC	Pen is geometric.
PS_COSMETIC	Pen is cosmetic.
The pen style can be any one of the following values:

Style	Description
PS_ALTERNATE	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.

Return Value

If the function succeeds, the return value is a handle that identifies a logical pen.

If the function fails, the return value is zero.

Remarks

A geometric pen can have any width and can have any of the attributes of a brush, such as dithers and patterns. A cosmetic pen can only be a single pixel wide and must be a solid color, but cosmetic pens are generally faster than geometric pens.

The width of a geometric pen is always specified in world units. The width of a cosmetic pen is always 1.

End cap and join are only specified for geometric pens.

After an application creates a logical pen, it can select that pen into a device context by calling the SelectObject function. After a pen is selected into a device context, it can be used to draw lines and curves.

If dwPenStyle is PS_COSMETIC and PS_USERSTYLE, the entries in the lpStyle array specify lengths of dashes and spaces in style units. A style unit is defined by the device where the pen is used to draw a line.

If dwPenStyle is PS_GEOMETRIC and PS_USERSTYLE, the entries in the lpStyle array specify lengths of dashes and spaces in logical units.

If dwPenStyle is PS_ALTERNATE, the style unit is ignored and every other pixel is set.

If the lbStyle member of the LOGBRUSH structure pointed to by lplb is BS_PATTERN, the bitmap pointed to by the lbHatch member of that structure cannot be a dib section. A dib section is a bitmap created by CreateDibSection. If that bitmap is a dib section, the ExtCreatePen function fails.

When an application no longer requires a given pen, it should call the DeleteObject function to delete the pen from the device context.

See Also

CreatePen, CreateDibSection, CreatePenIndirect, DeleteObject, GetObject, LOGBRUSH, SelectObject, SetMiterLimit


ExtCreateRegion

The ExtCreateRegion function creates a region from the specified region and transformation data.

HRGN ExtCreateRegion(

CONST XFORM *  lpXform,	// address of transformation data
DWORD  nCount,	// size of structure containing region data
CONST RGNDATA *  lpRgnData	// address of region data
);
Parameters

lpXform

Points to an XFORM structure that defines the transformation to be performed on the region. If this pointer is NULL, the identity transformation is used.

nCount

Specifies the number of bytes pointed to by lpRgnData.

lpRgnData

Points to a RGNDATA structure that contains the region data.

Return Value

If the function succeeds, the return value is the value of the region.

If the function fails, the return value is NULL.

Remarks

An application can retrieve data for a region by calling the GetRegionData function.

See Also

GetRegionData, RGNDATA, XFORM


ExtDeviceMode

The ExtDeviceMode function is not implemented in the Win32 API. Win32-based applications should use the DocumentProperties function.

See Also

GetRegionData, RGNDATA, XFORM


ExtensionPropSheetPageProc  (preliminaryWindows NT)
ExtensionPropSheetPageProc  (preliminary−Windows NT)

The ExtensionPropSheetPageProc function specifies an application-defined callback function that receives the address of the AddPropSheetPageProc function, which resides in the module that creates a property sheet. A property sheet extension must export the ExtensionPropSheetPageProc function.

BOOL CALLBACK ExtensionPropSheetPageProc(

LPVOID lpv,
LPFNADDPROPSHEETPAGE  lpfnAddPropSheetPageProc,
LPARAM  lParam
);
Parameters

lpv

Pointer to an application-defined value that describes an item for which a property sheet page is to be created. This parameter can be NULL.

lpfnAddPropSheetPageProc

Pointer to the AddPropSheetPageProc function. The extension dynamic-link library (DLL) calls this function to add a page to the property sheet.

lParam

Application-defined 32-bit value.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

AddPropSheetPageProc


ExtEscape

The ExtEscape function allows applications to access capabilities of a particular device that are not available through GDI.

int ExtEscape(

HDC  hdc,	// handle of device context
int  nEscape,	// escape function
int  cbInput,	// number of bytes in input structure
LPCSTR  lpszInData,	// address of input structure
int  cbOutput,	// number of bytes in output structure
LPSTR  lpszOutData	// address of output structure
);
Parameters

hdc

Identifies the device context.

nEscape

Specifies the escape function to be performed.

cbInput

Specifies the number of bytes of data pointed to by the lpszInData parameter.

lpszInData

Points to the input structure required for the specified escape.

cbOutput

Specifies the number of bytes of data pointed to by the lpszOutData parameter.

lpszOutData

Points to the structure that receives output from this escape. This parameter must not be NULL if ExtEscape is called as a query function. If no data is to be returned in this structure, set cbOutput to 0.

Return Value

The return value specifies the outcome of the function. It is greater than zero if the function is successful, except for the QUERYESCSUPPORT printer escape, which checks for implementation only. The return value is zero if the escape is not implemented. A return value less than zero indicates an error. To get extended error information, call GetLastError.

Remarks

Use this function to pass a driver-defined escape value to a device.

Use the Escape function to pass one of the escape values defined by Windows to a device. ExtEscape might not work properly with the escapes defined by Windows. In particular, escapes in which lpszInData points to a structure that contains a member that is a pointer will fail.

See Also

Escape, GetDeviceCaps


ExtFloodFill

The ExtFloodFill function fills an area of the display surface with the current brush.

BOOL ExtFloodFill(

HDC  hdc,	// handle 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
);
Parameters

hdc

Identifies a device context.

nXStart

Specifies the logical x-coordinate of the point where filling is to begin.

nYStart

Specifies the logical y-coordinate of the point where filling is to begin.

crColor

Specifies the color of the boundary or of the area to be filled. The interpretation of crColor depends on the value of the fuFillType parameter.

fuFillType

Specifies the type of fill operation to be performed. It must be one of the following values:

Value	Meaning
FLOODFILLBORDER	The fill area is bounded by the color specified by the crColor parameter. This style is identical to the filling performed by the FloodFill function.
FLOODFILLSURFACE	The fill area is defined by the color that is specified by crColor. Filling continues outward in all directions as long as the color is encountered. This style is useful for filling areas with multicolored boundaries.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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, use the GetDeviceCaps function.

See Also

FloodFill, GetDeviceCaps


ExtractAssociatedIcon

The ExtractAssociatedIcon function returns the handle of an indexed icon found in a file or an icon found in an associated executable file.

HICON ExtractAssociatedIcon(

HINSTANCE  hInst,	// application instance handle
LPTSTR  lpIconPath,	// path and filename of file for which icon is wanted
LPWORD  lpiIcon	// pointer to icon index
);
Parameters

hInst

Specifies the instance of the application calling the function.

lpIconPath

Points to a string that specifies the full path and filename of the file for which an icon is desired. The function extracts the icon handle from that file, or from an executable file associated with that file.

If the icon handle is obtained from an executable file, the function stores the full path and filename of that executable in the string pointed to by lpIconPath.

lpiIcon

Points to a WORD that specifies the index of the icon whose handle is to be obtained.

If the icon handle is obtained from an executable file, the function stores the icon's identifier in the WORD pointed to by lpiIcon.

Return Value

If the function succeeds, the return value is an icon handle. If the icon is extracted from an associated executable file, the function stores the full path and filename of the executable file in the string pointed to by lpIconPath, and stores the icon's identifier in the WORD pointed to by lpiIcon.

If the function fails, the return value is NULL.

Remarks

The ExtractAssociatedIcon function first looks for the indexed icon in the file specified by lpIconPath. If the function cannot obtain the icon handle from that file, and the file has an associated executable file, it looks in that executable file for an icon. Associations with executable files are based on filename extensions, are stored in the per-user part of the registry, and can be defined using File Manager's Associate command.

See Also

ExtractIcon


ExtractIcon

The ExtractIcon function retrieves the handle of an icon from the given executable file, dynamic-link library (DLL), or icon file.

HICON ExtractIcon(

HINSTANCE  hInst,	// instance handle
LPCTSTR  lpszExeFileName,	// filename of file with icon
UINT  nIconIndex	// index of icon to extract
);
Parameters

hInst

Identifies the instance of the application calling the function.

lpszExeFileName

Points to a null-terminated string specifying the name of an executable file, DLL, or icon file.

nIconIndex

Specifies the index of the icon to retrieve. If this value is 0, the function returns the handle of the first icon in the specified file. If this value is −1, the function returns the total number of icons in the specified file.

Return Value

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.


ExtSelectClipRgn

The ExtSelectClipRgn function combines the specified region with the current clipping region by using the specified mode.

int ExtSelectClipRgn(

HDC  hdc,	// handle of device context
HRGN  hrgn,	// handle of region
int  fnMode	// region-selection mode
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region to be selected. This handle can only be NULL when the RGN_COPY mode is specified.

fnMode

Specifies the operation to be performed. It must be one of the following values:

Value	Meaning
RGN_AND	The new clipping region combines the overlapping areas of the current clipping region and the region identified by hrgn.
RGN_COPY	The new clipping region is a copy of the region identified by hrgn. This is identical to SelectClipRgn. If the region identified by hrgn is NULL, the new clipping region is the default clipping region (the default clipping region is a null region).
RGN_DIFF	The new clipping region combines the areas of the current clipping region with those areas excluded from the region identified by hrgn.
RGN_OR	The new clipping region combines the current clipping region and the region identified by hrgn.
RGN_XOR	The new clipping region combines the current clipping region and the region identified by hrgn but excludes any overlapping areas.
Return Value

If the function succeeds, the return value specifies the new clipping region's complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred.
Remarks

If an error occurs when this function is called, the previous clipping region for the 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 region identified by the hrgn parameter is used. The region itself can be reused after this call or it can be deleted.

See Also

SelectClipRgn


ExtTextOut

The ExtTextOut function draws a character string by using the currently selected font. An optional rectangle may be provided, to be used for clipping, opaquing, or both.

BOOL ExtTextOut(

HDC  hdc,	// handle 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  lpString,	// points to string
UINT  cbCount,	// number of characters in string
CONST INT *  lpDx	// address of array of intercharacter spacing values
);
Parameters

hdc

Identifies the device context.

X

Specifies the logical x-coordinate of the reference point used to position the string.

Y

Specifies the logical y-coordinate of the reference point used to position the string.

fuOptions

Specifies how to use the application-defined rectangle. This parameter can be a combination of the following values:

Value	Meaning
ETO_CLIPPED	The text will be clipped to the rectangle.
ETO_GLYPH_INDEX	Windows 95: The lpString array refers to an array returned from GetCharacterPlacement and should be parsed directly by GDI as no further language-specific processing is required. Glyph indexing only applies to TrueType fonts, but the flag can be used for Windows bitmap and vector fonts to indicate no further language processing is necessary and GDI should process the string directly. Note that all glyph indices are 16-bit values even though the string is assumed to be an array of 8-bit values for raster fonts.
ETO_OPAQUE	The current background color should be used to fill the rectangle.
ETO_RTL	Windows 95: If this value is given and a Hebrew or Arabic font is selected into the device context, the string is output using right-to-left reading order. If this value is not given, the string is output in left- to-right order. The same effect can be achieved by setting the TA_RTLREADING value in SetTextAlign. This value is preserved for backward compatability.
The ETO_GLYPH_INDEX and ETO_RTL values cannot be used together. Because ETO_GLYPH_INDEX implies that all language processing has been completed, the function ignores the ETO_RTL flag if also given.

lprc

Points to an optional RECT structure that specifies the dimensions of a rectangle that is used for clipping, opaquing, or both.

lpString

Points to the character string to be drawn. The string does not need to be zero-terminated, since cbCount specifies the length of the string.

cbCount

Specifies the number of characters in the string.

lpDx

Points to an optional array of values that indicate the distance between origins of adjacent character cells. For example, lpDx[i] logical units separate the origins of character cell i and character cell i + 1.

Return Value

If the string is drawn, the return value is TRUE.

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

Remarks

The current text-alignment settings for the specified DC 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, RECT, SetTextAlign


FatalAppExit

The FatalAppExit function displays a message box and terminates the application when the message box is closed. If Windows is running with a kernel debugger, the message box gives the user the opportunity to terminate the application or to cancel the message box and return to the application that called FatalAppExit.

VOID FatalAppExit(

UINT  uAction,	// reserved
LPCTSTR  lpMessageText	// address of string to display in message box
);
Parameters

uAction

Reserved; must be zero.

lpMessageText

Points to a null-terminated string that is displayed in the message box. The message is displayed on a single line. To accommodate low-resolution screens, the string should be no more than 35 characters in length.

Return Value

This function does not return a value.

Remarks

An application calls FatalAppExit only when it is not capable of terminating any other way. FatalAppExit may not always free an application's memory or close its files, and it may cause a general failure of Windows. An application that encounters an unexpected error should terminate by freeing all its memory and returning from its main message loop.

See Also

FatalExit


FatalExit

The FatalExit function transfers execution control to the debugger. The behavior of the debugger thereafter is specific to the type of debugger used.

VOID FatalExit(

int  ExitCode	// error code
);
Parameters

ExitCode

Specifies the error code associated with the exit.

Return Value

This function does not return a value.

Remarks

An application should only use FatalExit for debugging purposes. It should not call the function in a retail version of the application because doing so will terminate the application.

See Also

FatalAppExit


FileIOCompletionRoutine

The FileIOCompletionRoutine function is called when an asynchronous input and output (I/O) function (ReadFileEx or WriteFileEx) is completed and the calling thread is in an alertable wait (using the SleepEx, WaitForSingleObjectEx, or WaitForMultipleObjectsEx function with the fAlertable flag set to TRUE).

VOID WINAPI FileIOCompletionRoutine(

DWORD  dwErrorCode,	// completion code
DWORD  dwNumberOfBytesTransfered,	// number of bytes transferred
LPOVERLAPPED  lpOverlapped	// address of structure with I/O information
);
Parameters

dwErrorCode

Specifies the I/O completion status. This parameter may be one of the following values:

Value	Meaning
0	The I/O was successful.
ERROR_HANDLE_EOF	The ReadFileEx function tried to read past the end of the file.
dwNumberOfBytesTransfered

Specifies the number of bytes transferred. If an error occurs, this parameter is zero.

lpOverlapped

Points to the OVERLAPPED structure specified by the asynchronous I/O function.

Windows does not use the hEvent member of the OVERLAPPED structure; the calling application may use this member to pass information to the completion routine. Windows does not use the OVERLAPPED structure after the completion routine is called, so the completion routine can deallocate the memory used by the overlapped structure.

Return Value

This function does not return a value.

Remarks

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

OVERLAPPED, ReadFileEx, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx


FileTimeToDosDateTime

The FileTimeToDosDateTime function converts a 64-bit file time to MS-DOS date and time values.

BOOL FileTimeToDosDateTime(

CONST FILETIME *  lpFileTime,	// address of 64-bit file time
LPWORD  lpFatDate,	// address of variable for MS-DOS date
LPWORD  lpFatTime	// address of variable for MS-DOS time
);
Parameters

lpFileTime

Points to a FILETIME structure containing the 64-bit file time to convert to MS-DOS date and time format. The FILETIME structure has the following form:

typedef struct _FILETIME { // ft

    DWORD dwLowDateTime;

    DWORD dwHighDateTime;

} FILETIME;

lpFatDate

Points to a variable to receive the MS-DOS date. The date is a packed 16-bit value with the following format:

Bits	Contents
0−4	Day of the month (1−31)
5−8	Month (1 = January, 2 = February, etc.)
9−15	Year offset from 1980 (add 1980 to get actual year)
lpFatTime

Points to a variable to receive the MS-DOS time. The time is a packed 16-bit value with the following format:

Bits	Contents
0−4	Second divided by 2
5−10	Minute (0−59)
11−15	Hour (0−23 on a 24-hour clock)
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The MS-DOS date format can represent only dates between 1/1/1980 and 12/31/2107; this conversion fails if the input file time is outside this range.

See Also

DosDateTimeToFileTime, FileTimeToSystemTime, SystemTimeToFileTime


FileTimeToLocalFileTime

The FileTimeToLocalFileTime function converts a file time based on the Coordinated Universal Time (UTC) to a local file time.

BOOL FileTimeToLocalFileTime(

CONST FILETIME *  lpFileTime,	// address of UTC file time to convert
LPFILETIME  lpLocalFileTime	// address of converted file time
);
Parameters

lpFileTime

Points to a FILETIME structure containing the UTC-based file time to be converted into a local file time.

lpLocalFileTime

Points to a FILETIME structure to receive the converted local file time. This parameter cannot be the same as the lpFileTime parameter.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

FILETIME, LocalFileTimeToFileTime


FileTimeToSystemTime

The FileTimeToSystemTime function converts a 64-bit file time to system time format.

BOOL FileTimeToSystemTime(

CONST FILETIME *  lpFileTime,	// pointer to file time to convert
LPSYSTEMTIME  lpSystemTime	// pointer to structure to receive system time
);
Parameters

lpFileTime

Pointer to a FILETIME structure containing the file time to convert to system date and time format.

The FileTimeToSystemTime function only works with FILETIME values that are less than 0x8000000000000000. The function fails with values equal to or greater than that.

lpSystemTime

Pointer to a SYSTEMTIME structure to receive the converted file time.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

As noted above, the function fails for FILETIME values that are equal to or greater than 0x8000000000000000.

See Also

DosDateTimeToFileTime, FILETIME, FileTimeToDosDateTime, SYSTEMTIME, SystemTimeToFileTime


FillConsoleOutputAttribute

The FillConsoleOutputAttribute function sets the text and background color attributes for a specified number of character cells, beginning at the specified coordinates in a screen buffer.

BOOL FillConsoleOutputAttribute(

HANDLE  hConsoleOutput,	// handle of screen buffer
WORD  wAttribute,	// color attribute to write
DWORD  nLength,	// number of character cells to write to
COORD  dwWriteCoord,	// x- and y-coordinates of first cell
LPDWORD  lpNumberOfAttrsWritten	// address of number of cells written to
);
Parameters

hConsoleOutput

Identifies a screen buffer. The handle must have GENERIC_WRITE access.

wAttribute

Specifies the foreground and background color attributes to write to the screen buffer. Any combination of the following values can be specified: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces white text on a black background:

FOREGROUND_RED | FOREGROUND_GREEN | FOREGROUND_BLUE

nLength

Specifies the number of character cells to be set to the specified color attributes.

dwWriteCoord

Specifies a COORD structure containing the screen buffer coordinates of the first cell whose attributes are to be set.

lpNumberOfAttrsWritten

Points to the variable that receives the number of character cells whose attributes were actually set.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the number of character cells whose attributes are to be set extends beyond the end of the specified row in the screen buffer, the cells of the next row are set. If the number of cells to write to extends beyond the end of the screen buffer, the cells are written up to the end of the screen buffer.

The character values at the positions written to are not changed.

See Also

COORD, FillConsoleOutputCharacter, SetConsoleTextAttribute, WriteConsoleOutputAttribute


FillConsoleOutputCharacter

The FillConsoleOutputCharacter function writes a character to the screen buffer a specified number of times, beginning at the specified coordinates.

BOOL FillConsoleOutputCharacter(

HANDLE  hConsoleOutput,	// handle of screen buffer
TCHAR  cCharacter,	// character to write
DWORD  nLength,	// number of character cells to write to
COORD  dwWriteCoord,	// x- and y-coordinates of first cell
LPDWORD  lpNumberOfCharsWritten	// address of number of cells written to
);
Parameters

hConsoleOutput

Identifies a screen buffer. The handle must have GENERIC_WRITE access.

cCharacter

Specifies the character to write to the screen buffer.

nLength

Specifies the number of character cells to write the character to.

dwWriteCoord

Specifies a COORD structure containing the screen buffer coordinates of the first cell to write the character to.

lpNumberOfCharsWritten

Points to the variable that receives the number of characters actually written to the screen buffer.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the 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

COORD, FillConsoleOutputAttribute, WriteConsoleOutputCharacter


FillMemory

The FillMemory function fills a block of memory with a specified value.

VOID FillMemory (

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
);
Parameters

Destination

Points to the starting address of the block of memory to fill.

Length

Specifies the size, in bytes, of the block of memory to fill.

Fill

Specifies the byte value with which to fill the memory block.

Return Value

This function has no return value.

See Also

CopyMemory, MoveMemory, ZeroMemory


FillPath

The FillPath function closes any open figures in the current path and fills the path's interior by using the current brush and polygon-filling mode.

BOOL FillPath(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies a device context (DC) that contains a valid path.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

After its interior is filled, the path is discarded from the DC identified by the hdc parameter.

See Also

BeginPath, SetPolyFillMode, StrokeAndFillPath, StrokePath


FillRect

The FillRect function fills a rectangle by using the specified brush. This function includes the left and top borders, but excludes the right and bottom borders of the rectangle.

int FillRect(

HDC  hDC,	// handle of device context
CONST RECT  *lprc,	// address of structure with rectangle
HBRUSH  hbr	// handle of brush
);
Parameters

hDC

Identifies the device context.

lprc

Points to a RECT structure that contains the logical coordinates of the rectangle to be filled.

hbr

Identifies the brush used to fill the rectangle.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The brush identified by the hbr parameter may be either a handle to a logical brush or a color value. If specifying a handle to a logical brush, call one of the following functions to obtain the handle: CreateHatchBrush, CreatePatternBrush, or CreateSolidBrush. Additionally, you may retrieve a handle to one of the stock brushes by using the GetStockObject function. If specifying a color value for the hbr parameter, it must be one of the standard system colors (the value 1 must be added to the chosen color). For example:

FillRect(hdc, &rect, (HBRUSH) (COLOR_ENDCOLORS+1));

For a list of all the standard system colors, see GetSysColor.

When filling the specified rectangle, FillRect does not include the rectangle's right and bottom sides. GDI fills a rectangle up to, but not including, the right column and bottom row, regardless of the current mapping mode.

See Also

CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, GetStockObject, RECT


FillRgn

The FillRgn function fills a region by using the specified brush.

BOOL FillRgn(

HDC  hdc,	// handle of device context
HRGN  hrgn,	// handle of region to be filled
HBRUSH  hbr	// handle of brush used to fill the region
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region to be filled. The region's coordinates are presumed to be in logical units.

hbr

Identifies the brush to be used to fill the region.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

CreateBrushIndirect, CreateDIBPatternBrush, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, PaintRgn


FindAtom

The FindAtom function searches the local atom table for the specified character string and retrieves the atom associated with that string.

ATOM FindAtom(

LPCTSTR  lpString	// address of string to find
);
Parameters

lpString

Points to the null-terminated character string to search for.

Return Value

If the function succeeds, the return value is the atom associated with the given string.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Even though Windows preserves the case of a string in an atom table, the search performed by the FindAtom function is not case sensitive.

See Also

AddAtom, DeleteAtom, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom


FindClose

The FindClose function closes the specified search handle. The FindFirstFile and FindNextFile functions use the search handle to locate files with names that match a given name.

BOOL FindClose(

HANDLE  hFindFile	// file search handle
);
Parameters

hFindFile

Identifies the search handle. This handle must have been previously opened by the FindFirstFile function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

After the FindClose function is called, the handle specified by the hFindFile parameter cannot be used in subsequent calls to either the FindNextFile or FindClose function.

See Also

FindFirstFile, FindNextFile


FindCloseChangeNotification

The FindCloseChangeNotification function stops change notification handle monitoring.

BOOL FindCloseChangeNotification(

HANDLE  hChangeHandle	// handle of change notification to close
);
Parameter

hChangeHandle

Identifies a change notification handle created by the FindFirstChangeNotification function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

After the FindCloseChangeNotification function is called, the handle specified by the hChangeHandle parameter cannot be used in subsequent calls to either the FindNextChangeNotification or FindCloseChangeNotification function.

See Also

FindFirstChangeNotification, FindNextChangeNotification, WaitForMultipleObjects, WaitForSingleObject


FindClosePrinterChangeNotification

The FindClosePrinterChangeNotification function closes a change notification object created by calling the FindFirstPrinterChangeNotification function. The printer or print server associated with the change notification object will no longer be monitored by that object.

BOOL FindClosePrinterChangeNotification(

HANDLE  hChange	// handle of change notification object to close
);
Parameter

hChange

Handle to the change notification object to be closed. This is a handle created by calling the FindFirstPrinterChangeNotification function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

After calling the FindClosePrinterChangeNotification function, you cannot use the hChange handle in subsequent calls to either FindFirstPrinterChangeNotification or FindNextPrinterChangeNotification.

The three Find*PrinterChangeNotification functions, in combination with the wait functions, provide an asynchronous, more resource-efficient alternative to the WaitForPrinterChange function.

See Also

FindFirstPrinterChangeNotification, FindNextPrinterChangeNotification, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForPrinterChange, WaitForSingleObject, WaitForSingleObjectEx


FindExecutable

The FindExecutable function retrieves the name and handle of the executable (.EXE) file associated with the specified filename.

HINSTANCE FindExecutable(

LPCTSTR  lpFile,	// address of string for filename
LPCTSTR  lpDirectory,	// address of string for default directory
LPTSTR  lpResult	// address of buffer for string for executable file on return
);
Parameters

lpFile

Points to a null-terminated string specifying a filename. This can be a document or executable file.

lpDirectory

Points to a null-terminated string specifying the default directory.

lpResult

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 lpFile parameter.

Return Value

The return value for the FindExecutable function if valid only if the function fails. If it does fail, the return value is less than or equal to 32. Possible error values are listed in the Remarks section.

Remarks

When FindExecutable returns, the lpResult parameter may contain the path to the DDE server started if no server responds to a request to initiate a DDE conversation.

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


FindFirstChangeNotification

The FindFirstChangeNotification function creates a change notification handle and sets up initial change notification filter conditions. A wait on a notification handle succeeds when a change matching the filter conditions occurs in the specified directory or subtree.

HANDLE FindFirstChangeNotification(

LPCTSTR  lpPathName,	// address of name of directory to watch
BOOL  bWatchSubtree,	// flag for monitoring directory or directory tree
DWORD  dwNotifyFilter	// filter conditions to watch for
);
Parameters

lpPathName

Points to a null-terminated string that specifies the path of the directory to watch.

bWatchSubtree

Specifies whether the function will monitor the directory or the directory tree. If this parameter is TRUE, the function monitors the directory tree rooted at the specified directory; if it is FALSE, it monitors only the specified directory.

dwNotifyFilter

Specifies the filter conditions that satisfy a change notification wait. This parameter can be one or more of the following values:

Value	Meaning
FILE_NOTIFY_CHANGE_FILE_NAME
	Any filename change in the watched directory or subtree satisfies a change notification wait. Changes include renames, creations, and deletions.
FILE_NOTIFY_CHANGE_DIR_NAME
	Any directory-name change in the watched directory or subtree satisfies a change notification wait. Changes include 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, detection occurs only when the cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_WRITE
	Any change to the last write-time of files in the watched directory or subtree 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, detection 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.
Return Value

If the function succeeds, the return value is a handle of a find change notification object.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The 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, it can be closed by using the FindCloseChangeNotification function.

See Also

FindCloseChangeNotification, FindNextChangeNotification, WaitForMultipleObjects, WaitForSingleObject


FindFirstFile

The FindFirstFile function searches a directory for a file whose name matches the specified filename. FindFirstFile examines subdirectory names as well as filenames.

HANDLE FindFirstFile(

LPCTSTR  lpFileName,	// address of name of file to search for
LPWIN32_FIND_DATA  lpFindFileData	// address of returned information
);
Parameters

lpFileName

Windows 95: Points to a null-terminated string that specifies a valid directory or path and filename, which can contain wildcard characters (* and ?). This string must not exceed MAX_PATH characters.

Windows NT: Points to a null-terminated string that specifies a valid directory or path and filename, which can contain wildcard characters (* and ?).

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the FindFirstFile function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) version of FindFirstFile and prepending "\\?\" to the path. The "\\?\" tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with FindFirstFileW. This also works with UNC names. The "\\?\" is ignored as part of the path. For example, "\\?\C:\myworld\private" is seen as "C:\myworld\private", and "\\?\UNC\bill_g_1\hotstuff\coolapps" is seen as "\\bill_g_1\hotstuff\coolapps".

lpFindFileData

Points to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory. The structure can be used in subsequent calls to the FindNextFile or FindClose function to refer to the file or subdirectory.

Return Value

If the function succeeds, the return value is a search handle used in a subsequent call to FindNextFile or FindClose.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The FindFirstFile function opens a search handle and returns information about the first file whose name matches the specified pattern. Once the search handle is established, you can use the FindNextFile function to search for other files that match the same pattern. When the search handle is no longer needed, close it by using the FindClose function.

This function searches for files by name only; it cannot be used for attribute-based searches.

See Also

FindClose, FindNextFile, GetFileAttributes, SetFileAttributes, WIN32_FIND_DATA


FindFirstFreeAce

The FindFirstFreeAce function retrieves a pointer to the first free byte in an access-control list (ACL).

BOOL FindFirstFreeAce(

PACL  pAcl,	// address of access-control list
LPVOID  *pAce	// address of pointer to first free byte
);
Parameters

pAcl

Points to an ACL structure.

pAce

Points to a pointer to the first free position in the ACL created when the function returns. If the ACL is invalid, this parameter is NULL. If the ACL is full, this parameter points to the byte immediately following the ACL.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

ACL, GetAce, GetAclInformation


FindFirstPrinterChangeNotification

The FindFirstPrinterChangeNotification function creates a change notification object and returns a handle to the object. You can then use this handle in a call to one of the wait functions to monitor changes to the printer or print server.

The FindFirstPrinterChangeNotification call specifies the type of changes to be monitored. You can specify a set of conditions to monitor for changes, a set of printer information fields to monitor, or both.

A wait operation on the change notification handle succeeds when one of the specified changes occurs in the specified printer or print server. You then call the FindNextPrinterChangeNotification function to retrieve information about the change, and to reset the change notification object for use in the next wait operation.

HANDLE FindFirstPrinterChangeNotification(

HANDLE  hPrinter,	// handle to printer or print server to monitor for changes
DWORD  fdwFlags,	// flags that specify the conditions to monitor
DWORD  fdwOptions,	// reserved, must be zero
LPVOID  pPrinterNotifyOptions	// pointer to structure specifying printer information to monitor
);
Parameters

hPrinter

Handle to the printer or print server that you want to monitor. This handle is obtained by calling the OpenPrinter function.

fdwFlags

A set of bit flags that specify the conditions that will cause the change notification object to enter a signaled state. A change notification occurs when one or more of the specified conditions are met. The fdwFlags parameter can be zero if pPrinterNotifyOptions is non-NULL.

You can set one or more of the following change notification constants:

Value	Meaning
PRINTER_CHANGE_FORM
	Notify of any changes to a form. You can set this general flag or one or more of the following specific flags: PRINTER_CHANGE_ADD_FORM PRINTER_CHANGE_SET_FORM PRINTER_CHANGE_DELETE_FORM
PRINTER_CHANGE_JOB
	Notify of any changes to a job. You can set this general flag or one or more of the following specific flags: PRINTER_CHANGE_ADD_JOB PRINTER_CHANGE_SET_JOB PRINTER_CHANGE_DELETE_JOB PRINTER_CHANGE_WRITE_JOB
PRINTER_CHANGE_PORT
	Notify of any changes to a port. You can set this general flag or one or more of the following specific flags: PRINTER_CHANGE_ADD_PORT PRINTER_CHANGE_CONFIGURE_PORT PRINTER_CHANGE_DELETE_PORT
PRINTER_CHANGE_PRINT_PROCESSOR
	Notify of any changes to a print processor. You can set this general flag or one or more of the following specific flags: PRINTER_CHANGE_ADD_PRINT_PROCESSOR PRINTER_CHANGE_DELETE_PRINT_PROCESSOR
PRINTER_CHANGE_PRINTER
	Notify of any changes to a printer. You can set this general flag or one or more of the following specific flags:  PRINTER_CHANGE_ADD_PRINTER PRINTER_CHANGE_SET_PRINTER PRINTER_CHANGE_DELETE_PRINTER PRINTER_CHANGE_FAILED_CONNECTION_PRINTER
PRINTER_CHANGE_PRINTER_DRIVER
	Notify of any changes to a printer driver. You can set this general flag or one or more of the following specific flags: PRINTER_CHANGE_ADD_PRINTER_DRIVER PRINTER_CHANGE_SET_PRINTER_DRIVER PRINTER_CHANGE_DELETE_PRINTER_DRIVER
PRINTER_CHANGE_ALL
	Notify if any of the preceding changes occur.
For descriptions of the more specific flags in the preceding table, see the FindNextPrinterChangeNotification function.

fdwOptions

Reserved; must be zero.

pPrinterNotifyOptions

Pointer to a PRINTER_NOTIFY_OPTIONS structure. The pTypes member of this structure points to an array of one or more PRINTER_NOTIFY_OPTIONS_TYPE structures, each of which specifies a printer information field to monitor. A change notification occurs when one or more of the specified fields changes. When a change occurs, the FindNextPrinterChangeNotification function can retrieve the new printer information. This parameter can be NULL if fdwFlags is nonzero.

For a list of fields that can be monitored, see PRINTER_NOTIFY_OPTIONS_TYPE

Return Value

If the function succeeds, the return value is a handle to a change notification object associated with the specified printer or print server.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

To monitor a printer or print server, call the FindFirstPrinterChangeNotification function, then use the returned change notification object handle in a call to one of the wait functions:WaitForSingleObject, WaitForSingleObjectEx, WaitForMultipleObjects, or WaitForMultipleObjectsEx. A wait operation on a change notification object is satisfied when the change notification object enters the signaled state. The system signals the object when one or more of the changes specified by fdwFlags or pPrinterNotifyOptions occurs in the monitored printer or print server.

When you call FindFirstPrinterChangeNotification, either fdwFlags must be nonzero or pPrinterNotifyOptions must be non-NULL. If both are specified, notifications will occur for both.

When a wait operation on a printer change notification object is satisfied, call the FindNextPrinterChangeNotification function to determine the cause of the notification. For a condition specified by fdwFlags, FindNextPrinterChangeNotification reports the condition or conditions that changed. For a printer information field specified by pPrinterNotifyOptions , FindNextPrinterChangeNotification reports the field or fields that changed as well as the new information for these fields. FindNextPrinterChangeNotification also resets the change notification object to the nonsignaled state so you can use it in another wait operation to continue monitoring the printer or print server.

Do not call the FindNextPrinterChangeNotification function if the change notification object is not in the signaled state. If the wait function returns the value WAIT_TIMEOUT, the change object is not in the signaled state. Call the FindNextPrinterChangeNotification function only if the wait function succeeds without timing out.

When you no longer need the change notification object, close it by calling the FindClosePrinterChangeNotification function.

The three Find*PrinterChangeNotification functions, in combination with the wait functions, provide an asynchronous and resource-efficient alternative to the WaitForPrinterChange function.

See Also

FindClosePrinterChangeNotification, FindNextPrinterChangeNotification, OpenPrinter, PRINTER_NOTIFY_OPTIONS, PRINTER_NOTIFY_OPTIONS_TYPE, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForPrinterChange, WaitForSingleObject, WaitForSingleObjectEx


FindNextChangeNotification

The FindNextChangeNotification function requests that the operating system signal a change notification handle the next time it detects an appropriate change.

BOOL FindNextChangeNotification(

HANDLE  hChangeHandle	// handle of change notification to signal
);
Parameters

hChangeHandle

Identifies a change notification handle created by the FindFirstChangeNotification function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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.

FindNextChangeNotification should not be used 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 hChangeHandle is no longer needed, close it by using the FindCloseChangeNotification function.

See Also

FindCloseChangeNotification, FindFirstChangeNotification, WaitForMultipleObjects, WaitForSingleObject


FindNextFile

The FindNextFile function continues a file search from a previous call to the FindFirstFile function.

BOOL FindNextFile(

HANDLE  hFindFile,	// handle of search
LPWIN32_FIND_DATA  lpFindFileData	// address of structure for data on found file
);
Parameters

hFindFile

Identifies a search handle returned by a previous call to the FindFirstFile function.

lpFindFileData

Points to the WIN32_FIND_DATA structure that receives information about the found file or subdirectory. The structure can be used in subsequent calls to FindNextFile to refer to the found file or directory.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. If no matching files can be found, the GetLastError function returns ERROR_NO_MORE_FILES.

Remarks

The FindNextFile function searches for files by name only; it cannot be used for attribute-based searches.

See Also

FindClose, FindFirstFile, GetFileAttributes, SetFileAttributes, WIN32_FIND_DATA


FindNextPrinterChangeNotification

The FindNextPrinterChangeNotification function retrieves information about the most recent change notification for a change notification object associated with a printer or print server. Call this function when a wait operation on the change notification object is satisfied.

The function also resets the change notification object to the not-signaled state. You can then use the object in another wait operation to continue monitoring the printer or print server. The operating system will set the object to the signaled state the next time one of a specified set of changes occurs to the printer or print server. The FindFirstPrinterChangeNotification function creates the change notification object and specifies the set of changes to be monitored.

BOOL FindNextPrinterChangeNotification(

HANDLE  hChange,	// handle to change notification object of interest
PDWORD  pdwChange	// pointer to a value that indicates the condition that changed
LPVOID  pPrinterNotifyOptions,	// pointer to a structure that specifies a refresh flag
LPVOID  *ppPrinterNotifyInfo,	// pointer to a pointer that receives printer information buffer
);
Parameters

hChange

Handle to a change notification object associated with a printer or print server. You obtain such a handle by calling the FindFirstPrinterChangeNotification function. The operating system sets this change notification object to the signaled state when it detects one of the changes specified in the object's change notification filter.

pdwChange

Pointer to a doubleword variable whose bits are set to indicate the changes that occurred to cause the most recent notification. The bit flags that might be set correspond to those specified in the fdwFlags parameter of the FindFirstPrinterChangeNotification call. You can set one or more of the following bit flags:

Value	Meaning
PRINTER_CHANGE_ADD_FORM
	A form was added to the server.
PRINTER_CHANGE_ADD_JOB
	A print job was sent to the printer.
PRINTER_CHANGE_ADD_PORT
	A port or monitor was added to the server.
PRINTER_CHANGE_ADD_PRINT_PROCESSOR
	A print processor was added to the server.
PRINTER_CHANGE_ADD_PRINTER
	A printer was added to the server.
PRINTER_CHANGE_ADD_PRINTER_DRIVER
	A printer driver was added to the server.
PRINTER_CHANGE_CONFIGURE_PORT
	A port was configured on the server.
PRINTER_CHANGE_DELETE_FORM
	A form was deleted from the server.
PRINTER_CHANGE_DELETE_JOB
	A job was deleted.
PRINTER_CHANGE_DELETE_PORT
	A port or monitor was deleted from the server.
PRINTER_CHANGE_DELETE_PRINT_PROCESSOR
	A print processor was deleted from the server.
PRINTER_CHANGE_DELETE_PRINTER
	A printer was deleted.
PRINTER_CHANGE_DELETE_PRINTER_DRIVER
	A printer driver was deleted from the server.
PRINTER_CHANGE_SET_FORM
	A form was set on the server.
PRINTER_CHANGE_SET_JOB
	A job was set.
PRINTER_CHANGE_SET_PRINTER
	A printer was set.
PRINTER_CHANGE_WRITE_JOB
	Job data was written.
pPrinterNotifyOptions

Pointer to a PRINTER_NOTIFY_OPTIONS structure. Set the Flags member of this structure to PRINTER_NOTIFY_OPTIONS_REFRESH, to cause the function to return the current data for all monitored printer information fields. The function ignores all other members of the structure. This parameter can be NULL.

ppPrinterNotifyInfo

Pointer to a pointer variable that receives the address of a system-allocated, read-only buffer. Call the FreePrinterNotifyInfo function to free the buffer when you are finished with it. This parameter can be NULL if no information is required.

The buffer contains a PRINTER_NOTIFY_INFO structure, which contains an array of PRINTER_NOTIFY_INFO_DATA structures. Each element of the array contains information about one of the fields specified in the pPrinterNotifyOptions parameter of the FindFirstPrinterChangeNotification call. Typically, the function provides data only for the fields that changed to cause the most recent notification. However, if the structure pointed to by the pPrinterNotifyOptions parameter specifies PRINTER_NOTIFY_OPTIONS_REFRESH, the function provides data for all monitored fields.

If the PRINTER_NOTIFY_INFO_DISCARDED bit is set in the Flags member of the PRINTER_NOTIFY_INFO structure, an overflow or error occurred, and notifications may have been lost. In this case, no additional notifications will be sent until you make a second FindNextPrinterChangeNotification call that specifies PRINTER_NOTIFY_OPTIONS_REFRESH.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Call the FindNextPrinterChangeNotification function after a wait operation on a notification object created by FindFirstPrinterChangeNotification has been satisfied. Calling FindNextPrinterChangeNotification lets you obtain information about the change that satisfied the wait operation, and resets the notification object so it can be signaled when the next change occurs.

Do not call the FindNextPrinterChangeNotification function if the change notification object is not in the signaled state. If a wait function returns the value WAIT_TIMEOUT, the change object is not in the signaled state. Call the FindNextPrinterChangeNotification function only if the wait function succeeds without timing out.

To continue monitoring the printer or print server for changes, repeat the cycle of calling one of the wait functions, and then calling the FindNextPrinterChangeNotification function to examine the change and reset the notification object. The wait functions are WaitForSingleObject, WaitForSingleObjectEx, WaitForMultipleObjects, and WaitForMultipleObjectsEx.

When you no longer need the change notification object, close it by calling the FindClosePrinterChangeNotification function.

The three Find*PrinterChangeNotification functions, in combination with the wait functions, provide an asynchronous, more resource-efficient alternative to the WaitForPrinterChange function.

See Also

FindClosePrinterChangeNotification, FindFirstPrinterChangeNotification, PRINTER_NOTIFY_INFO, PRINTER_NOTIFY_INFO_DATA, PRINTER_NOTIFY_OPTIONS, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForPrinterChange, WaitForSingleObject, WaitForSingleObjectEx


FindResource

The FindResource function determines the location of a resource with the specified type and name in the specified module.

HRSRC FindResource(

HMODULE  hModule,	// resource-module handle
LPCTSTR  lpName,	// address of resource name
LPCTSTR  lpType	// address of resource type
);
Parameters

hModule

Identifies the module whose executable file contains the resource.

lpName

Specifies the name of the resource. For more information, see the Remarks section.

lpType

Specifies the resource type. For more information, see the Remarks section. For standard resource types, this parameter can be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_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
Return Value

If the function succeeds, the return value is a handle to the specified resource's info block. To obtain a handle to the resource, pass this handle to the LoadResource function.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If the high-order word of the lpName or lpType parameter is zero, the low-order word specifies the integer identifier of the name or type of the given resource. Otherwise, those parameters are long pointers to null-terminated strings. If the first character of the string is a pound sign (#), the remaining characters represent a decimal number that specifies the integer identifier of the resource's name or type. For example, the string "#258" represents the integer identifier 258.

An application should reduce the amount of memory required for the resources by referring to them by integer identifier instead of by name.

An application can use FindResource to find any type of resource, but this function should be used only if the application must access the binary resource data when making subsequent calls to LoadLibrary and LockResource.

To use a resource immediately, an application should use one of the following resource-specific functions to find and load the resources in one call:

Function	Action
FormatMessage	Loads and formats a message-table entry.
LoadAccelerators	Loads an accelerator table.
LoadBitmap	Loads a bitmap resource.
LoadCursor	Loads a cursor resource.
LoadIcon	Loads an icon resource.
LoadMenu	Loads a menu resource.
LoadString	Loads a string-table entry.
For example, an application can use the LoadIcon function to load an icon for display on the screen. However, the application should use FindResource and LoadResource if it is loading the icon to copy its data to another application.

See Also

FindResourceEx, FormatMessage, LoadAccelerators, LoadBitmap, LoadCursor, LoadIcon, LoadMenu, LoadResource, LoadString, LockResource, SizeofResource


FindResourceEx

The FindResourceEx function determines the location of the resource with the specified type, name, and language in the specified module.

HRSRC FindResourceEx(

HMODULE  hModule,	// resource-module handle
LPCTSTR  lpType,	// address of resource type
LPCTSTR  lpName,	// address of resource name
WORD  wLanguage	// resource language
);
Parameters

hModule

Identifies the module whose executable file contains the resource. If this parameter is NULL, the function searches the module used to create the current process.

lpType

Points to a null-terminated string specifying the type name of the resource. For more information, see the Remarks section. For standard resource types, this parameter can be one of the following values:

Value	Meaning
RT_ACCELERATOR	Accelerator table
RT_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
lpName

Points to a null-terminated string specifying the name of the resource. For more information, see the Remarks section.

wLanguage

Specifies the language of the resource. If this parameter is MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL), the current language associated with the calling thread is used.

To specify a language other than the current language, use the MAKELANGID macro to create this parameter. For more information, see the MAKELANGID macro.

Return Value

If the function succeeds, the return value is a handle to the specified resource's info block. To obtain a handle to the resource, pass this handle to the LoadResource function.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If the high-word of the lpType or lpName parameter is zero, the low-word specifies the integer identifier of the type or name of the given resource. Otherwise, those parameters are pointers to null-terminated strings. If the first character of the string is a pound sign (#), the remaining characters represent a decimal number that specifies the integer identifier of the resource's name or type. For example, the string "#258" represents the integer identifier 258.

Applications should reduce the amount of memory required for the resources by referring to them by integer identifier instead of by name.

An application can use FindResource to find any type of resource, but this function should be used only if the application must access the binary resource data when making subsequent calls to the LoadLibrary and LockResource functions.

To use a resource immediately, an application should use the following resource-specific functions to find and load the resources in one call:

Function	Action
FormatMessage	Loads and formats a message-table entry.
LoadAccelerators	Loads an accelerator table.
LoadBitmap	Loads a bitmap resource.
LoadCursor	Loads a cursor resource.
LoadIcon	Loads an icon resource.
LoadMenu	Loads a menu resource.
LoadString	Loads a string-table entry.
For example, an application can use the LoadIcon function to load an icon for display on the screen. However, the application should use FindResource and LoadResource if it is loading the icon to copy its data to another application.

See Also

FindResource, FormatMessage, LoadAccelerators, LoadBitmap, LoadCursor, LoadIcon, LoadMenu, LoadString, LoadResource, MAKELANGID


FindText

The FindText function creates a system-defined modeless dialog box that enables the user to find text within a document.

HWND FindText(

LPFINDREPLACE  lpfr	// address of structure with initialization data
);
Parameter

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.

Return Value

If the function succeeds, the return value is the window handle of the dialog box.

If the function fails, the return value is NULL. To get extended error information, call CommDlgExtendedError. CommDlgExtendedError may return one of the following error codes:

CDERR_FINDRESFAILURE	CDERR_MEMLOCKFAILURE
CDERR_INITIALIZATION	CDERR_NOHINSTANCE
CDERR_LOCKRESFAILURE	CDERR_NOHOOK
CDERR_LOADRESFAILURE	CDERR_NOTEMPLATE
CDERR_LOADSTRFAILURE	CDERR_STRUCTSIZE
CDERR_MEMALLOCFAILURE	FRERR_BUFFERLENGTHZERO
Remarks

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 the 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, the function must return a handle of the brush that should be used to paint the control background.

See Also

CommDlgExtendedError, FINDREPLACE, IsDialogMessage, RegisterWindowMessage, ReplaceText, WM_CTLCOLORDLG,


FindWindow

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.

HWND FindWindow(

LPCTSTR  lpClassName,	// address of class name
LPCTSTR  lpWindowName	// address of window name
);
Parameters

lpClassName

Points to a null-terminated string that specifies the class name or is an atom that identifies the class-name string. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word of lpClassName; the high-order word must be zero.

lpWindowName

Points to a null-terminated string that specifies the window name (the window's title). If this parameter is NULL, all window names match.

Return Value

If the function succeeds, the return value is the handle of the window that has the specified class name and window name.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

EnumWindows, FindWindowEx, GetClassName, GlobalAddAtom


FindWindowEx  (preliminaryWindows 95)
FindWindowEx  (preliminary−Windows 95)

The FindWindowEx function retrieves the handle of a window whose class name and window name match the specified strings. The function searches child windows, beginning with the one following the given child window.

HWND FindWindowEx(

HWND  hwndParent,	// handle of parent window
HWND  hwndChildAfter,	// handle of a child window
LPCTSTR  lpszClass,	// address of class name
LPCTSTR  lpszWindow	// address of window name
);
Parameters

hwndParent

Identifies the parent window whose child windows are to be searched.

If hwndParent is NULL, the function uses the desktop window as the parent window. The function searches among windows that are child windows of the desktop.

hwndChildAfter

Identifies a child window. The search begins with the next child window in the Z order. hwndChildAfter must be a direct child window of hwndParent, not just a descendant window.

If hwndChildAfter is NULL, the search begins with the first child window of hwndParent.

Note that if both hwndParent and hwndChildAfter are NULL, the function searches all top-level windows.

lpszClass

Points to a null-terminated string that specifies the class name or is an atom that identifies the class-name string. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be placed in the low-order word of lpszClass; the high-order word must be zero.

lpszWindow

Points to a null-terminated string that specifies the window name (the window's title). If this parameter is NULL, all window names match.

Return Value

If the function succeeds, the return value is the handle of the window that has the specified class and window names.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

EnumWindows, FindWindow, GetClassName, GlobalAddAtom


FixBrushOrgEx

The FixBrushOrgEx function is not implemented in the Win32 API. It is provided for compatibility with Win32s. If called, the function does nothing, and returns FALSE.

See Also

GetBrushOrgEx, SetBrushOrgEx


FlashWindow

The FlashWindow function flashes the specified window once.

BOOL FlashWindow(

HWND  hWnd,	// handle of window to flash
BOOL  bInvert	// flash status
);
Parameters

hWnd

Identifies the window to be flashed. The window can be either open or minimized (iconic).

bInvert

Specifies whether the window is to be flashed or returned to its original state. The window is flashed from one state to the other if this parameter is TRUE. If this parameter is FALSE, the window is returned to its original state (either active or inactive).

Return Value

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.

Remarks

Flashing a window means changing the appearance of its caption bar as if the window were changing from inactive to active status, or vice versa. (An inactive caption bar changes to an active caption bar; an active caption bar changes to an inactive caption bar.)

Typically, a window is flashed to inform the user that the window requires attention but that it does not currently have the keyboard focus.

The FlashWindow function flashes the window only once; for repeated flashing, the application should create a system timer.

This function always returns TRUE for iconic windows. If the window is iconic, FlashWindow simply flashes the icon; the bInvert parameter is ignored for iconic windows.


FlattenPath

The FlattenPath function transforms any curves in the path that is selected into the current device context (DC), turning each curve into a sequence of lines.

BOOL FlattenPath(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies a DC that contains a valid path.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

See Also

WidenPath


FloodFill

The FloodFill function fills an area of the display surface with the current brush. The area is assumed to be bounded as specified by the crFill parameter.

The FloodFill function is included only for compatibility with earlier versions of Windows. For Win32-based applications, use the ExtFloodFill function with FLOODFILLBORDER specified.

BOOL FloodFill(

HDC  hdc,	// handle of device context
int  nXStart,	// x-coordinate, where fill begins
int  nYStart,	// y-coordinate, where fill begins
COLORREF  crFill	// fill color
);
Parameters

hdc

Identifies a device context.

nXStart

Specifies the logical x-coordinate of the point where filling is to begin.

nYStart

Specifies the logical y-coordinate of the point where filling is to begin.

crFill

Specifies the color of the boundary or of the area to be filled.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Following are reasons this function might fail:

•	The fill could not be completed.

•	The given point has the boundary color specified by the crFill parameter.

•	The given point lies outside the current clipping region — that is, it is not visible on the device.

See Also

ExtFloodFill


FlushConsoleInputBuffer

The FlushConsoleInputBuffer function flushes the console input buffer. All input records currently in the input buffer are discarded.

BOOL FlushConsoleInputBuffer(

HANDLE  hConsoleInput	// handle of console input buffer
);
Parameters

hConsoleInput

Identifies the console input buffer. The handle must have GENERIC_WRITE access.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetNumberOfConsoleInputEvents, PeekConsoleInput, ReadConsoleInput, WriteConsoleInput


FlushFileBuffers

The FlushFileBuffers function clears the buffers for the specified file and causes all buffered data to be written to the file.

BOOL FlushFileBuffers(

HANDLE  hFile	// open handle to file whose buffers are to be flushed
);
Parameters

hFile

An open file handle. The function flushes this file's buffers. The file handle must have GENERIC_WRITE access to the file.

If hFile is a handle to a communications device, the function only flushes the transmit buffer.

If hFile is a handle to the server end of a named pipe, the function does not return until the client has read all buffered data from the pipe.

Windows NT: The function fails if hFile is a handle to console output. That is because console output is not buffered. The function returns FALSE, and GetLastError returns ERROR_INVALID_HANDLE.

Windows 95: The function does nothing if hFile is a handle to console output. That is because console output is not buffered. The function returns TRUE, but it does nothing.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The WriteFile and WriteFileEx functions typically write data to an internal buffer that the operating system writes to disk on a regular basis. The FlushFileBuffers function writes all of the buffered information for the specified file to disk.

You can pass the same file handle used with the _lread, _lwrite, _lcreat, and related functions to FlushFileBuffers.

See Also

_lread, _lwrite, _lcreat, WriteFile, WriteFileEx


FlushInstructionCache

The FlushInstructionCache function flushes the instruction cache for the specified process.

BOOL FlushInstructionCache(

HANDLE  hProcess,	// handle of process with cache to flush
LPCVOID  lpBaseAddress,	// address of region to flush
DWORD  dwSize	// length of region to flush
);
Parameters

hProcess

Identifies the process that has an instruction cache to flush.

lpBaseAddress

Points to the base of the region to be flushed. This parameter can be NULL.

dwSize

Specifies the length of the region to be flushed if the lpBaseAddress parameter is not NULL.

Return Value

If the function succeeds, the return value is TRUE.

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


FlushViewOfFile

The FlushViewOfFile function writes to the disk a byte range within a mapped view of a file.

BOOL FlushViewOfFile(

LPCVOID  lpBaseAddress,	// start address of byte range to flush
DWORD  dwNumberOfBytesToFlush	// number of bytes in range
);
Parameters

lpBaseAddress

Points to the base address of the byte range to be flushed to the disk representation of the mapped file.

dwNumberOfBytesToFlush

Specifies the number of bytes to flush.

If dwNumberOfBytesToFlush is zero, the file is flushed from the base address to the end of the mapping.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Flushing a range of a mapped view causes any dirty pages within that range to be written to the disk. Dirty pages are those whose contents have changed since the file view was mapped.

See Also

MapViewOfFile, UnmapViewOfFile


FMExtensionProc

The FMExtensionProc function is an application-defined callback function that processes menu commands and messages sent to a File Manager extension dynamic-link library (DLL).

LONG WINAPI FMExtensionProc(

HWND  hwnd,	// handle of extension window
WORD  wEvent,	// menu-item identifier, or message
LONG  lParam	// additional message information
);
Parameters

hwnd

Identifies the File Manager window. An extension DLL should use this handle to specify the owner for any dialog box or message box that the DLL may display and to send request messages to File Manager.

wEvent

Specifies the message. This parameter can be one of the following values:

Value	Meaning
1−99	The user selected the menu item identified by this number.
FMEVENT_INITMENU	User selected the extension's menu.
FMEVENT_LOAD	File Manager is loading the extension DLL.
FMEVENT_SELCHANGE	Selection changed in File Manager's directory window or in Search Results window.
FMEVENT_UNLOAD	File Manager is unloading the extension DLL.
FMEVENT_USER_REFRESH	User chose the Refresh command from the Window menu.
lParam

Specifies 32 bits of additional message-specific information.

Return Value

The callback function should return the result of the message processing. The actual return value depends on the message processed.

Remarks

Whenever File Manager calls the FMExtensionProc function, it waits to refresh its directory windows (for changes in the file system) until after the function returns. This allows the extension to perform large numbers of file operations without excessive repainting by File Manager. It is not necessary for the extension to send the FM_REFRESH_WINDOWS message to notify File Manager to repaint its windows.


FoldString

The FoldString function maps one string to another, performing a specified transformation option.

int FoldString(

DWORD  dwMapFlags,	// mapping transformation options
LPCTSTR  lpSrcStr,	// address of source string
int  cchSrc,	// size of source string, in bytes or characters
LPTSTR  lpDestStr,	// address of destination buffer
int  cchDest	// size of destination buffer, in bytes or characters
);
Parameters

dwMapFlags

A set of bit flags that indicate the type of transformation to be used during mapping. This value can be a combination of the following bit-flag constants:

Option	Meaning
MAP_FOLDCZONE	Fold compatibility zone characters into standard Unicode equivalents. For information about compatibility zone characters, see the following Remarks section.
MAP_FOLDDIGITS	Map all digits to Unicode characters 0 through 9.
MAP_PRECOMPOSED	Map accented characters to precomposed characters, in which the accent and base character are combined into a single character value. This value cannot be combined with MAP_COMPOSITE.
MAP_COMPOSITE	Map accented characters to composite characters, in which the accent and base character are represented by two character values. This value cannot be combined with MAP_PRECOMPOSED.
lpSrcStr

Points to the string to be mapped.

cchSrc

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpSrcStr buffer. If cchSrc is −1, lpSrcStr is assumed to be null-terminated, and the length is calculated automatically.

lpDestStr

Points to the buffer to store the mapped string.

cchDest

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpDestStr buffer. If cchDest is zero, the function returns the number of bytes or characters required to hold the mapped string, and the buffer pointed to by lpDestStr is not used.

Return Value

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the destination buffer, or if the cchDest parameter is zero, the number of bytes or characters required to hold the mapped string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

The mapped string is null-terminated if the source string is null-terminated.

The lpSrcStr and lpDestStr pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The compatibility zone in Unicode consists of characters in the range 0xF900 through 0xFFEF that are assigned to characters from other character-encoding standards but are actually variants of characters that are already in Unicode. The compatibility zone is used to support round-trip mapping to these standards. Applications can use the MAP_FOLDCZONE flag to avoid supporting the duplication of characters in the compatibility zone.

See Also

LCMapString, CompareString


ForegroundIdleProc

The ForegroundIdleProc hook procedure is an application-defined callback function the system calls whenever the 32-bit foreground thread is about to become idle.

DWORD ForegroundIdleProc(

int  code,	// hook code
DWORD  wParam,	// not used
LONG  lParam	// not used
);
Parameters

code

Specifies whether the hook procedure must process the message. If code is HC_ACTION, the hook procedure must process the message. If code is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Not used.

lParam

Not used.

Remarks

An application installs this hook procedure by specifying the WH_FOREGROUNDIDLE hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

ForegroundIdleProc is a placeholder for the application-defined function name.

This is a thread-specific hook.

See Also

CallNextHookEx, SetWindowsHookEx


FormatMessage

The FormatMessage function formats a message string. The function requires a message definition as input. The message definition can come from a buffer passed into the function. It can come from a message table resource in an already-loaded module. Or the caller can ask the function to search the system's message table resource(s) for the message definition. The function finds the message definition in a message table resource based on a message identifier and a language identifier. The function copies the formatted message text to an output buffer, processing any embedded insert sequences if requested.

DWORD FormatMessage(

DWORD  dwFlags,	// source and processing options
LPCVOID  lpSource,	// 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
);
Parameters

dwFlags

Contains a set of bit flags that specify aspects of the formatting process and how to interpret the lpSource parameter. The low-order byte of dwFlags specifies how the function handles line breaks in the output buffer. The low-order byte can also specify the maximum width of a formatted output line.

You can specify a combination of the following bit flags:

Value	Meaning
FORMAT_MESSAGE_ALLOCATE_BUFFER
	Specifies that the lpBuffer parameter is a pointer to a PVOID pointer, and that the nSize parameter specifies the minimum number of bytes (ANSI version) or characters (Unicode version) to allocate for an output message buffer. The function allocates a buffer large enough to hold the formatted message, and places a pointer to the allocated buffer at the address specified by lpBuffer. The caller should use the LocalFree function to free the buffer when it is no longer needed.
FORMAT_MESSAGE_IGNORE_INSERTS
	Specifies that insert sequences in the message definition are to be ignored and passed through to the output buffer unchanged. This flag is useful for fetching a message for later formatting. If this flag is set, the Arguments parameter is ignored.
FORMAT_MESSAGE_FROM_STRING
	Specifies that lpSource is a pointer to a null-terminated message definition. The message definition may contain insert sequences, just as the message text in a message table resource may. Cannot be used with FORMAT_MESSAGE_FROM_HMODULE or FORMAT_MESSAGE_FROM_SYSTEM.
FORMAT_MESSAGE_FROM_HMODULE
	Specifies that lpSource is a module handle containing the message-table resource(s) to search. If this lpSource handle is NULL, the current process's application image file will be searched. Cannot be used with FORMAT_MESSAGE_FROM_STRING.
FORMAT_MESSAGE_FROM_SYSTEM
	Specifies that the function should search the system message-table resource(s) for the requested message. If this flag is specified with FORMAT_MESSAGE_FROM_HMODULE, the function searches the system message table if the message is not found in the module specified by lpSource. Cannot be used with FORMAT_MESSAGE_FROM_STRING. If this flag is specified, an application can pass the result of the GetLastError function to retrieve the message text for a system-defined error.
FORMAT_MESSAGE_ARGUMENT_ARRAY
	Specifies that the Arguments parameter is not a va_list structure, but instead is just a pointer to an array of 32-bit values that represent the arguments.
The low-order byte of dwFlags can specify the maximum width of a formatted output line. Use the FORMAT_MESSAGE_MAX_WIDTH_MASK constant and bitwise Boolean operations to set and retrieve this maximum width value.

The following table shows how FormatMessage interprets the value of the low-order byte.

Value	Meaning
0	There are no output line width restrictions. The function stores line breaks that are in the message definition text into the output buffer.
a nonzero value other than FORMAT_MESSAGE_MAX_WIDTH_MASK	The nonzero value is the maximum number of characters in an output line. The function ignores regular line breaks in the message definition text. The function never splits a string delimited by white space across a line break. The function stores hard-coded line breaks in the message definition text into the output buffer. Hard-coded line breaks are coded with the %n escape sequence.
FORMAT_MESSAGE_MAX_WIDTH_MASK	The function ignores regular line breaks in the message definition text. The function stores hard-coded line breaks in the message definition text into the output buffer. The function generates no new line breaks.
lpSource

Specifies the location of the message definition. The type of this parameter depends upon the settings in the dwFlags parameter.

dwFlags Setting	Parameter Type
FORMAT_MESSAGE_FROM_HMODULE	lpSource is an hModule of the module that contains the message table to search.
FORMAT_MESSAGE_FROM_STRING	lpSource is an LPTSTR that points to unformatted message text. It will be scanned for inserts and formatted accordingly.
If neither of these flags is set in dwFlags, then lpSource is ignored.

dwMessageId

Specifies the 32-bit message identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.

dwLanguageId

Specifies the 32-bit language identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING.

lpBuffer

Points to a buffer for the formatted (and null-terminated) message. If dwFlags includes FORMAT_MESSAGE_ALLOCATE_BUFFER, the function allocates a buffer using the LocalAlloc function, and places the address of the buffer at the address specified in lpBuffer.

nSize

If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter specifies the maximum number of bytes (ANSI version) or characters (Unicode version) that can be stored in the output buffer. If FORMAT_MESSAGE_ALLOCATE_BUFFER is set, this parameter specifies the minimum number of bytes or characters to allocate for an output buffer.

Arguments

Points to an array of 32-bit values that are used as insert values in the formatted message. %1 in the format string indicates the first value in the Arguments array; %2 indicates the second argument; and so on.

The interpretation of each 32-bit value depends on the formatting information associated with the insert in the message definition. The default is to treat each value as a pointer to a null-terminated string.

By default, the Arguments parameter is of type va_list*, which is a language- and implementation-specific data type for describing a variable number of arguments. If you do not have a pointer of type va_list*, then specify the FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array of 32-bit values; those values are input to the message formatted as the insert values.

Return Value

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) stored in the output buffer, excluding the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

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, LocalFree


FrameRect

The FrameRect function draws a border around the specified rectangle by using the specified brush. The width and height of the border are always one logical unit.

int FrameRect(

HDC  hDC,	// handle of device context
CONST RECT  * lprc,	// address of rectangle coordinates
HBRUSH  hbr	// handle of brush
);
Parameters

hDC

Identifies the device context in which the border is drawn.

lprc

Points to a RECT structure that contains the logical coordinates of the upper-left and lower-right corners of the rectangle.

hbr

Identifies the brush used to draw the border.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The brush identified by the hbr parameter must have been created by using the CreateHatchBrush, CreatePatternBrush, or CreateSolidBrush function, or retrieved by using the GetStockObject function.

If the bottom member of the RECT structure is less than or equal to the top member, or if the right member is less than or equal to the left member, the function does not draw the rectangle.

See Also

CreateHatchBrush, CreatePatternBrush, CreateSolidBrush, GetStockObject, RECT


FrameRgn

The FrameRgn function draws a border around the specified region by using the specified brush.

BOOL FrameRgn(

HDC  hdc,	// handle 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
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region to be enclosed in a border. The region's coordinates are presumed to be in logical units.

hbr

Identifies the brush to be used to draw the border.

nWidth

Specifies the width, in logical units, of vertical brush strokes.

nHeight

Specifies the height, in logical units, of horizontal brush strokes.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

FillRgn, PaintRgn


FreeConsole

The FreeConsole function detaches the calling process from its console.

BOOL FreeConsole(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If other processes share the console, the console is not destroyed, but the calling process cannot refer to it.

A process can use FreeConsole to detach itself from its current console, and then it can call the AllocConsole function to create a new console.

See Also

AllocConsole


FreeDDElParam

The FreeDDElParam function frees the memory specified by the lParam parameter of a posted DDE message. An application receiving a posted DDE message should call this function after it has used the UnpackDDElParam function to unpack the lParam value.

BOOL FreeDDElParam(

UINT  msg,	// posted DDE message
LONG  lParam	// lParam of message
);
Parameters

msg

Specifies the posted DDE message.

lParam

Specifies the lParam parameter of the posted DDE message.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

An application should call this function only for posted DDE messages.

This function frees the memory specified by the lParam parameter. It does not free the contents of lParam.

See Also

PackDDElParam, ReuseDDElParam, UnpackDDElParam


FreeEnvironmentStrings

The FreeEnvironmentStrings function frees a block of environment strings.

BOOL FreeEnvironmentStrings(

LPTSTR  lpszEnvironmentBlock	// pointer to a block of environment strings
);
Parameters

lpszEnvironmentBlock

Pointer to a block of environment strings. The pointer to the block must be obtained by calling the GetEnvironmentStrings function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

When GetEnvironmentStrings is called, it allocates memory for a block of environment strings. When the block is no longer needed, it should be freed by calling FreeEnvironmentStrings.

See Also

GetEnvironmentStrings


FreeImageColorMatcher  (preliminaryWindows 95)
FreeImageColorMatcher  (preliminary−Windows 95)

The FreeImageColorMatcher function frees the specified image color matcher, removing it from memory and freeing any internal resources associated with it.

BOOL FreeImageColorMatcher(

HANDLE hImageColorMatcher
);
Parameters

hImageColorMatcher

Handle to the image color matcher to unload.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The FreeImageColorMatcher function frees the image color matcher only if the reference count for the matcher is zero. The function always decrements the reference count by one before checking its value.


FreeLibrary

The FreeLibrary function decrements the reference count of the loaded dynamic-link library (DLL) module. When the reference count reaches zero, the module is unmapped from the address space of the calling process and the handle is no longer valid. This function supersedes the FreeModule function.

BOOL FreeLibrary(

HMODULE  hLibModule	// handle of loaded library module
);
Parameters

hLibModule

Identifies the loaded library module. The LoadLibrary or GetModuleHandle function returns this handle.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Each process maintains a reference count for each loaded library module. This reference count is incremented each time LoadLibrary is called and is decremented each time FreeLibrary is called. A DLL module loaded at process initialization due to load-time dynamic linking has a reference count of one. This count is incremented if the same module is loaded by a call to LoadLibrary.

Before unmapping a library module, the system enables the DLL to detach from the process by calling the DLL's DllEntryPoint function, if it has one, with the DLL_PROCESS_DETACH value. Doing so gives the DLL an opportunity to clean up resources allocated on behalf of the current process. After the entry-point function returns, the library module is removed from the address space of the current process.

Calling FreeLibrary does not affect other processes using the same library module.

See Also

DllEntryPoint, FreeLibraryAndExitThread, FreeModule, GetModuleHandle, LoadLibrary


FreeLibraryAndExitThread

The FreeLibraryAndExitThread function decrements the reference count of a loaded dynamic-link library (DLL) by one, and then calls ExitThread to terminate the calling thread. The function does not return.

The FreeLibraryAndExitThread function gives threads that are created and executed within a dynamic-link library an opportunity to safely unload the DLL and terminate themselves.

VOID FreeLibraryAndExitThread(

HMODULE  hLibModule,	// dynamic-link library whose reference count is to decrement
DWORD  dwExitCode	// exit code for thread
);
Parameters

hLibModule

Specifies the dynamic-link library module whose reference count the function decrements.

dwExitCode

Specifies the exit code for the calling thread.

Return Value

The function has no return value. The function does not return. Invalid hLibModule handles are ignored.

Remarks

The FreeLibraryAndExitThread function is implemented as:

    FreeLibrary(hLibModule);

    ExitThread(dwExitCode);

Refer to the reference pages for FreeLibrary and ExitThread for further information on those functions.

See Also

FreeLibrary, ExitThread, DisableThreadLibraryCalls


FreeModule

The FreeModule function is obsolete.

This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the FreeLibrary function.


FreePrinterNotifyInfo

The FreePrinterNotifyInfo function frees a system-allocated buffer that was returned by the FindNextPrinterChangeNotification function.

BOOL FreePrinterNotifyInfo(

PPRINTER_NOTIFY_INFO  pPrinterNotifyInfo	// pointer to a PRINTER_NOTIFY_INFO buffer
);
Parameters

pPrinterNotifyInfo

Pointer to a PRINTER_NOTIFY_INFO buffer returned from a call to the FindNextPrinterChangeNotification function. FreePrinterNotifyInfo deallocates this buffer.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

FindNextPrinterChangeNotification, PRINTER_NOTIFY_INFO


FreeProcInstance

The FreeProcInstance function is obsolete.

This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should not use this function; it has no meaning in the 32-bit environment.


FreeResource

The FreeResource function is obsolete. It is provided to simplify porting of 16-bit Windows-based applications. It is not necessary for Win32-based applications to free resources loaded by using the LoadResource function.

See Also

LoadResource, LockResource


FreeSelector

The FreeSelector function has been deleted.


FreeSid

The FreeSid function frees a security identifier (SID) previously allocated by using the AllocateAndInitializeSid function.

PVOID FreeSid(

PSID  pSid	// address of SID to free
);
Parameters

pSid

Points to the SID structure to free.

Return Value

This function does not return a value.

See Also

AllocateAndInitializeSid, SID


FSCTL_DISMOUNT_VOLUME

dwIoControlCode = FSCTL_DISMOUNT_VOLUME;   // 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; not used; must be NULL

cbOutBuffer ;       // size of output buffer; not used; must be zero

lpcbBytesReturned ; // address of actual bytes of output; not used; must be NULL

The FSCTL_DISMOUNT_VOLUME DeviceIoControl operation dismounts a volume.

Parameters

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. Not used with this operation. Set to NULL.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

The hDevice handle passed to DeviceIoControl must be a handle to a volume, opened for direct access. An application can obtain such a handle by calling CreateFile with lpszName set to a string that looks like this:

\\.\X:

where X is a hard-drive partition letter, floppy disk drive, or CD-ROM drive. The application must also specify the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the fdwShareMode parameter of CreateFile.

If the specified volume is locked, the operation fails.

A dismounted volume has the following properties:

•	There are no open files.

•	The operating system does not "know" about the volume.

The operating system tries to mount an unmounted volume as soon as any attempt is made to access it. For example, a call to GetLogicalDrives triggers the operating system to mount any unmounted volumes.

Dismounting a volume is useful whenever a volume needs to disappear for a while. For example, an application that changes a volume's file system from FAT to NTFS might follow these steps:

1.	Open the volume

2.	Lock the volume

3.	Format the volume

4.	Unlock the volume

5.	Dismount the volume

6.	Close the volume handle

A dismounting operation removes the volume from the FAT file system's "awareness." When the operating system mounts the volume, it appears as an NTFS volume.

See Also

CreateFile, DeviceIoControl, ExitThread, GetLogicalDrives


FSCTL_GET_COMPRESSION  (preliminaryWindows NT)
FSCTL_GET_COMPRESSION  (preliminary−Windows NT)

dwIoControlCode = FSCTL_GET_COMPRESSION;   // 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 FSCTL_GET_COMPRESSION DeviceIoControl operation obtains the current compression state of a file or directory on a volume whose file system supports per-stream compression.

Parameters

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 receives a USHORT indicating the current compression state of the file or directory.

The following values are defined:

Value	Meaning
0	The file or directory is not compressed.
1	The file or directory is compressed, using its parent directory's default compression format.
all other values	The file or directory is compressed, using the compression format specified by this value.
cbOutBuffer

Specifies the size, in bytes, of the buffer pointed to by lpvOutBuffer. The buffer  must be large enough to contain one USHORT value.

lpcbBytesReturned

Points to a DWORD value that receives the actual size, in bytes, of the data stored into the buffer pointed to by lpvOutBuffer.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

If the file system of the volume containing the specified file or directory does not support per-file or per-directory compression, the FSCTL_GET_COMPRESSION operation fails.

Windows NT version 3.51 supports file compression on volumes formatted with the NTFS file system.

You can set the compression state of a file or directory by using the FSCTL_SET_COMPRESSION DeviceIoControl operation. You can also compress or uncompress a file with that operation.

You can obtain the compression attribute of a file or directory by calling the GetFileAttributes function. The compression attribute indicates whether a file or directory is compressed. The compression state indicates whether a file or directory is compressed, and, if it is, the format of the compressed data.

See Also

DeviceIoControl, FSCTL_SET_COMPRESSION, GetFileAttributes


FSCTL_LOCK_VOLUME

dwIoControlCode = FSCTL_LOCK_VOLUME;   // 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; not used; must be NULL

cbOutBuffer ;       // size of output buffer; not used; must be zero

lpcbBytesReturned ; // address of actual bytes of output; not used; must be NULL

The FSCTL_LOCK_VOLUME DeviceIoControl operation locks a volume. A locked volume can be accessed only through handles to the file object (*hDevice) that locks the volume.

Parameters

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 in lpvOutBuffer. Not used with this operation. Set to NULL.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

The hDevice handle passed to DeviceIoControl must be a handle to a volume, opened for direct access. An application can obtain such a handle by calling CreateFile with lpszName set to a string that looks like this:

\\.\X:

where X is a hard-drive partition letter, floppy disk drive, or CD-ROM drive. The application must also specify the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the fdwShareMode parameter of CreateFile.

The FSCTL_LOCK_VOLUME operation fails if there are any open files on the volume. Conversely, success of this operation indicates there are no open files.

The operation is useful for applications that need exclusive access to a volume for a period of time—for example, disk utility programs.

A locked volume remains locked until one of the following occurs:

•	The application invokes the FSCTL_UNLOCK_VOLUME DeviceIoControl operation to unlock the volume.

•	The handle closes, either directly through CloseHandle, or indirectly when a process terminates.

The system flushes all cached data to the volume before locking it. For example, any data held in a lazy-write cache is written to the volume.

See Also

CloseHandle, CreateFile, DeviceIoControl, FSCTL_UNLOCK_VOLUME


FSCTL_SET_COMPRESSION  (preliminaryWindows NT)
FSCTL_SET_COMPRESSION  (preliminary−Windows NT)

dwIoControlCode = FSCTL_SET_COMPRESSION;   // 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 ;  // pointer to result of operation

The FSCTL_SET_COMPRESSION DeviceIoControl operation sets the compression state of a file or directory on a volume whose file system supports per-file and per-directory compression. You can use this operation to compress or uncompress a file or directory on such a volume.

Parameters

lpvInBuffer

Points to a buffer that contains a USHORT that specifies a new compression state for the file or directory.

The following values are defined:

Value	Meaning
0	Uncompress the file or directory.
1	Compress the file or directory, using its parent directory's default compression format.
all other values	Compress the file or directory, using the compression format specified by this value.
cbInBuffer

Specifies the size, in bytes, of the buffer pointed to by lpvInBuffer. The buffer must be large enough to contain one USHORT value.

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 result of the I/O control operation.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

If the file system of the volume containing the specified file or directory does not support per-file or per-directory compression, the FSCTL_SET_COMPRESSION operation fails.

Windows NT release 3.51 supports file compression on volumes formatted with the NTFS file system.

The compression state change of the file or directory occurs synchronously with the call to DeviceIoControl.

You can obtain the compression state of a file or directory by using the FSCTL_GET_COMPRESSION DeviceIoControl operation.

You can obtain the compression attribute of a file or directory by calling the GetFileAttributes function. The compression attribute indicates whether a file or directory is compressed. The compression state indicates whether a file or directory is compressed and, if it is, the format of the compressed data.

See Also

DeviceIoControl, FSCTL_GET_COMPRESSION, GetFileAttributes


FSCTL_UNLOCK_VOLUME

dwIoControlCode = FSCTL_UNLOCK_VOLUME;   // 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; not used; must be NULL

cbOutBuffer ;       // size of output buffer; not used; must be zero

lpcbBytesReturned ; // address of actual bytes of output; not used; must be NULL

The FSCTL_UNLOCK_VOLUME DeviceIoControl operation unlocks a volume.

Parameters

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 in lpvOutBuffer. Not used with this operation. Set to NULL.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

An application can call the FSCTL_LOCK_VOLUME DeviceIoControl operation to lock a volume.

The hDevice handle passed to DeviceIoControl must be a handle to a volume, opened for direct access. An application can obtain such a handle by calling CreateFile with lpszName set to a string that looks like this:

\\.\X:

where X is a hard-drive partition letter, floppy disk drive, or CD-ROM drive. The application must also specify the FILE_SHARE_READ and FILE_SHARE_WRITE flags in the fdwShareMode parameter of CreateFile.

See Also

CreateFile, DeviceIoControl, FSCTL_LOCK_VOLUME


GdiComment

The GdiComment function copies a comment from a buffer into a specified enhanced-format metafile.

BOOL GdiComment(

HDC  hdc,	// handle of a device context
UINT  cbSize,	// size of text buffer
CONST BYTE *  lpData	// address of text buffer
);
Parameters

hdc

Identifies an enhanced-metafile device context.

cbSize

Specifies the length of the comment buffer, in bytes.

lpData

Points to the buffer that contains the comment.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

A comment can include any kind of private information — for example, the source of a picture and the date it was created. A comment should begin with an application signature, followed by the data.

Comments should not contain application-specific or position-specific data. Position-specific data specifies the location of a record, and it should not be included because one metafile may be embedded within another metafile.

A public comment is a comment that begins with the comment signature identifier GDICOMMENT_IDENTIFIER. The following public comments are defined:

Comment	Description
GDICOMMENT_WINDOWS_METAFILE
	The GDICOMMENT_WINDOWS_METAFILE public comment contains a Windows-format metafile that is equivalent to an enhanced-format metafile. This comment is written only by the SetWinMetaFileBits function. The comment record, if given, follows the ENHMETAHEADER metafile record. The comment has the following form:
DWORD ident;         // This contains GDICOMMENT_IDENTIFIER.

DWORD iComment;      // This contains GDICOMMENT_WINDOWS_METAFILE.

DWORD nVersion;      // This contains the version number of the

                     // Windows-format metafile.

DWORD nChecksum;     // This is the additive DWORD checksum for

                     // the enhanced metafile.  The checksum

                     // for the enhanced metafile data including

                     // this comment record must be zero.

                     // Otherwise, the enhanced metafile has been

                     //  modified and the Windows-format

                     // metafile is no longer valid.

DWORD fFlags;        // This must be zero.

DWORD cbWinMetaFile; // This is the size, in bytes. of the

                     // Windows-format metafile data that follows.

GDICOMMENT_BEGINGROUP
	The GDICOMMENT_BEGINGROUP public comment identifies the beginning of a group of drawing records. It identifies an object within an enhanced metafile. The comment has the following form:
DWORD   ident;         // This contains GDICOMMENT_IDENTIFIER.

DWORD   iComment;      // This contains GDICOMMENT_BEGINGROUP.

RECTL   rclOutput;     // This is the bounding rectangle for the

                       // object in logical coordinates.

DWORD   nDescription;  // This is the number of characters in the

                       // optional Unicode description string that

                       // follows. This is zero if there is no

                       // description string.

GDICOMMENT_ENDGROUP
	The GDICOMMENT_ENDGROUP public comment identifies the end of a group of drawing records. The GDICOMMENT_BEGINGROUP comment and the GDICOMMENT_ENDGROUP comment must be included in a pair and may be nested. The comment has the following form:
DWORD   ident;       // This contains GDICOMMENT_IDENTIFIER.

DWORD   iComment;    // This contains GDICOMMENT_ENDGROUP.

GDICOMMENT_MULTIFORMATS
	The GDICOMMENT_MULTIFORMATS public comment allows multiple definitions of a picture to be included in an enhanced metafile. Using this comment, for example, an application can include an encapsulated PostScript definition as well as an enhanced metafile definition of a picture. When the record is played back, GDI selects and renders the first format recognized by the device. The comment has the following form:
DWORD   ident;          // This contains GDICOMMENT_IDENTIFIER.

DWORD   iComment;       // This contains GDICOMMENT_MULTIFORMATS.

RECTL   rclOutput;      // This is the bounding rectangle for the

                        // picture in logical coordinates.

DWORD   nFormats;       // This contains the number of formats in

                        // the comment.

EMRFORMAT aemrformat[1];// This is an array of EMRFORMAT structures

                        // in the order of preference.  The data

                        // for each format follows the last

                        // EMRFORMAT structure.

The EMRFORMAT structure has the following form:

typedef struct tagEMRFORMAT   {

    DWORD   dSignature;

    DWORD   nVersion;

    DWORD   cbData;

    DWORD   offData;

} EMRFORMAT;

See Also

CreateEnhMetaFile, EMRFORMAT, SetWinMetaFileBits


GdiFlush

The GdiFlush function flushes the calling thread's current batch.

BOOL GdiFlush(VOID)

Parameters

This function has no parameters.

Return Value

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.

Remarks

Batching enhances drawing performance by minimizing the amount of time needed to call GDI drawing functions that return Boolean values. The system accumulates the parameters for calls to these functions in the current batch and then calls the functions when the batch is flushed by any of the following means:

•	Calling the GdiFlush function

•	Reaching or exceeding the batch limit set by the GdiSetBatchLimit function

•	Filling the batching buffers

•	Calling any GDI function that does not return a Boolean value

The return value for GdiFlush applies only to the functions in the batch at the time GdiFlush is called. Errors that occur when the batch is flushed by any other means are never reported.

The GdiGetBatchLimit function returns the batch limit.

Note that the batch limit is maintained for each thread separately. In order to completely disable batching, call GdiSetBatchLimit(1) during the initialization of each thread.

An application should call GdiFlush before a thread goes away if there is a possibility that there are pending function calls in the graphics batch queue. The operating system does not execute such batched functions when a thread goes away.

A multithreaded application that serializes access to GDI objects with a mutex must ensure flushing the GDI batch queue by calling GdiFlush as each thread releases ownership of the GDI object. This prevents collisions of the GDI objects (device contexts, metafiles, and so on).

See Also

GdiGetBatchLimit, GdiSetBatchLimit


GdiGetBatchLimit

The GdiGetBatchLimit function returns the maximum number of function calls that can be accumulated in the calling thread's current batch. The system flushes the current batch whenever this limit is exceeded.

DWORD GdiGetBatchLimit(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the batch limit.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The batch limit is set by using the GdiSetBatchLimit function. Setting the limit to 1 effectively disables batching.

Only GDI drawing functions that return Boolean values can be batched; calls to any other GDI functions immediately flush the current batch. Exceeding the batch limit or calling the GdiFlush function also flushes the current batch.

When the system batches a function call, the function returns TRUE. The actual return value for the function is reported only if GdiFlush is used to flush the batch.

Note that the batch limit is maintained for each thread separately. In order to completely disable batching, call GdiSetBatchLimit(1) during the initialization of each thread.

See Also

GdiFlush, GdiSetBatchLimit


GdiSetBatchLimit

The GdiSetBatchLimit function sets the maximum number of functions that can be accumulated in the calling thread's current batch. The system flushes the current batch whenever this limit is exceeded.

DWORD GdiSetBatchLimit(

DWORD  dwLimit	// batch limit
);
Parameters

dwLimit

Specifies the batch limit to be set. A value of 0 sets the default limit. A value of 1 disables batching.

Return Value

If the function succeeds, the return value is the previous batch limit.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Only GDI drawing functions that return Boolean values can be accumulated in the current batch; calls to any other GDI functions immediately flush the current batch. Exceeding the batch limit or calling the GdiFlush function also flushes the current batch.

When the system accumulates a function, the function returns TRUE to indicate it is in the batch. When the system flushes the current batch and executes the function for the second time, the return value is either TRUE or FALSE, depending on whether the function succeeds. This second return value is reported only if GdiFlush is used to flush the batch.

Note that the batch limit is maintained for each thread separately. In order to completely disable batching, call GdiSetBatchLimit(1) during the initialization of each thread.

See Also

GdiFlush, GdiGetBatchLimit


GenerateConsoleCtrlEvent

The GenerateConsoleCtrlEvent function sends a specified signal to a console process group that shares the console associated with the calling process.

BOOL GenerateConsoleCtrlEvent(

DWORD  dwCtrlEvent,	// signal to generate
DWORD  dwProcessGroupId	// process group to get signal
);
Parameters

dwCtrlEvent

Specifies the type of signal to generate. One of the following values is specified:

Value	Meaning
CTRL_C_EVENT	Generates a CTRL+C signal.
CTRL_BREAK_EVENT	Generates a CTRL+BREAK signal.
dwProcessGroupId

Specifies the identifier of the process group that receives the signal. A process group is created when the CREATE_NEW_PROCESS_GROUP flag is specified in a call to the CreateProcess function. The process identifier of the new process is also the process group identifier of a new process group. The process group includes all processes that are descendants of the root process. Only those processes in the group that share the same console as the calling process receive the signal. In other words, if a process in the group creates a new console, that process does not receive the signal, nor do its descendants.

If this parameter is zero, the signal is generated in all processes that share the console of the calling process.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

GenerateConsoleCtrlEvent causes the control handler functions of processes in the target group to be called. All console processes have a default handler function that calls the ExitProcess function. A console process can use the SetConsoleCtrlHandler function to install or remove other handler functions.

SetConsoleCtrlHandler can also enable an inheritable attribute that causes the calling process to ignore CTRL+C signals. If GenerateConsoleCtrlEvent sends a CTRL+C signal to a process for which this attribute is enabled, the handler functions for that process are not called. CTRL+BREAK signals always cause the handler functions to be called.

See Also

CreateProcess, ExitProcess, SetConsoleCtrlHandler


GetAce

The GetAce function obtains a pointer to an ACE in an ACL.

An ACE is an access control entry. An ACL is an access control list.

BOOL GetAce(

PACL  pAcl,	// address of access-control list
DWORD  dwAceIndex,	// index of ACE to retrieve
LPVOID  *pAce	// address of pointer to ACE
);
Parameters

pAcl

Points to an ACL structure containing the ACE to be retrieved.

dwAceIndex

Specifies the ACE to which a pointer is retrieved. A value of 0 corresponds to the first ACE in the ACL, 1 to the second ACE, and so on.

pAce

Points to a pointer the function sets to the address of the ACE.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

ACL, AddAccessAllowedAce, AddAccessDeniedAce, AddAce, AddAuditAccessAce, GetAclInformation, InitializeAcl


GetAclInformation

The GetAclInformation function retrieves information about an access-control list (ACL).

BOOL GetAclInformation(

PACL  pAcl,	// address of access-control list
LPVOID  pAclInformation,	// address of ACL information
DWORD  nAclInformationLength,	// size of ACL information
ACL_INFORMATION_CLASS  dwAclInformationClass	// class of requested information
);
Parameters

pAcl

Points to an ACL structure. The function retrieves information about this ACL.

pAclInformation

Points to a buffer receiving the requested information. The structure put into the buffer depends on the information class requested in the dwAclInformationClass parameter.

nAclInformationLength

Specifies the size, in bytes, of the buffer pointed to by the pAclInformation parameter.

dwAclInformationClass

Specifies an ACL_INFORMATION_CLASS enumerated type that gives the class of information requested. This parameter can be one of two values from this enumerated type. If the value is AclRevisionInformation, the function fills the buffer pointed to by the pAclInformation parameter with an ACL_REVISION_INFORMATION structure.

If the value is AclSizeInformation, the function fills the buffer pointed to by the pAclInformation parameter with an ACL_SIZE_INFORMATION structure.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

ACL, ACL_REVISION_INFORMATION, ACL_SIZE_INFORMATION, GetAce, InitializeAcl, IsValidAcl, SetAclInformation


GetACP

The GetACP function retrieves the current ANSI code-page identifier for the system.

UINT GetACP(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the current ANSI code-page identifier for the system, or a default identifier if no code page is current.

Remarks

Following are the ANSI code-page identifiers:

Identifier	Meaning
874	Thai
932	Japan
936	Chinese (PRC, Singapore)
949	Korean
950	Chinese (Taiwan, Hong Kong)
1200	Unicode (BMP of ISO 10646)
1250	Windows 3.1 Eastern European
1251	Windows 3.1 Cyrillic
1252	Windows 3.1 Latin 1 (US, Western Europe)
1253	Windows 3.1 Greek
1254	Windows 3.1 Turkish
1255	Hebrew
1256	Arabic
1257	Baltic
See Also

GetCPInfo, GetOEMCP


GetActiveWindow

The GetActiveWindow function retrieves the window handle of the active window associated with the thread that calls the function.

HWND GetActiveWindow(VOID)

Parameters

This function has no parameters.

Return Value

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


GetAddressByName
GetAddressByName  (preliminary−Windows NT)

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

INT GetAddressByName(

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

dwNameSpace

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

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

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

lpServiceType

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

lpServiceName

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

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

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

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

lpiProtocols

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

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

dwResolution

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

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

Reserved for future use; must be set to NULL.

lpCsaddrBuffer

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

lpdwBufferLength

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

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

lpAliasBuffer

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

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

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

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

lpdwAliasBufferLength

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

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

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

Return Value

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

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

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

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

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

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

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

See Also

gethostbyname, CSADDR_INFO


GetArcDirection

The GetArcDirection function returns the current arc direction for the specified device context. Arc and rectangle functions use the arc direction.

int GetArcDirection(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value specifies the current arc direction. Following are the valid return values:

Value	Meaning
AD_COUNTERCLOCKWISE	Arcs and rectangles are drawn counterclockwise.
AD_CLOCKWISE	Arcs and rectangles are drawn clockwise.
If an error occurs, the return value is zero.

See Also

SetArcDirection


GetAspectRatioFilter

The GetAspectRatioFilter function is not implemented in the Win32 API. Win32-based applications should use the GetAspectRatioFilterEx function.


GetAspectRatioFilterEx

The GetAspectRatioFilterEx function retrieves the setting for the current aspect-ratio filter.

BOOL GetAspectRatioFilterEx(

HDC  hdc,	// handle of device context
LPSIZE  lpAspectRatio	// address of aspect-ratio filter
);
Parameters

hdc

Identifies a device context.

lpAspectRatio

Points to a SIZE structure that receives the current aspect-ratio filter.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The aspect ratio is the ratio formed by the width and height of a pixel on a given device.

Windows provides a special filter, the aspect-ratio filter, to select fonts that were designed for a particular device. An application can specify that Windows should only retrieve fonts matching the specified aspect ratio by calling the SetMapperFlags function.

See Also

SetMapperFlags, SIZE


GetAsyncKeyState

The GetAsyncKeyState function determines whether a key is up or down at the time the function is called, and whether the key was pressed after a previous call to GetAsyncKeyState.

SHORT GetAsyncKeyState(

int  vKey	// virtual-key code
);
Parameters

vKey

Specifies one of 256 possible virtual-key codes.

Windows NT: You can use left- and right-distinguishing constants to specify certain keys. See the Remarks section for further information.

Windows 95: Windows 95 does not support the left- and right-distinguishing constants available on Windows NT.

Return Value

If the function succeeds, the return value specifies whether the key was pressed since the last call to GetAsyncKeyState, and whether the key is currently up or down. If the most significant bit is set, the key is down, and if the least significant bit is set, the key was pressed after the previous call to GetAsyncKeyState. The return value is zero if a window in another thread or process currently has the keyboard focus.

Windows 95: Windows 95 does not support the left- and right-distinguishing constants. If you call GetAsyncKeyState on the Windows 95 platform with these constants, the return value is zero.

Remarks

You can use the virtual-key code constants VK_SHIFT, VK_CONTROL, and VK_MENU as values for the vKey parameter. This gives the state of the SHIFT, CTRL, or ALT keys without distinguishing between left and right.

Windows NT: You can use the following virtual-key code constants as values for vKey to distinguish between the left and right instances of those keys:

VK_LSHIFT	VK_RSHIFT
VK_LCONTROL	VK_RCONTROL
VK_LMENU	VK_RMENU
These left- and right-distinguishing constants are only available when you call the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

Windows 95: Windows 95 does not support the left- and right-distinguishing constants, and returns 0 when you use these constants.

The GetAsyncKeyState function works with mouse buttons. However, it checks on the state of the physical mouse buttons, not on the logical mouse buttons that the physical buttons are mapped to. For example, the call GetAsyncKeyState(VK_LBUTTON) always returns the state of the left physical mouse button, which may mapped to the left or right logical mouse button. You can determine the system's current mapping of physical mouse buttons to logical mouse buttons by calling

GetSystemMetrics(SM_SWAPBUTTON)

which returns TRUE if the mouse buttons have been swapped.

See Also

GetKeyboardState, GetKeyState, GetSystemMetrics, MapVirtualKey, SetKeyboardState


GetAtomHandle

The GetAtomHandle function is not implemented in the Win32 API. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the GetAtomName function.


GetAtomName

The GetAtomName function retrieves a copy of the character string associated with the specified local atom. This function replaces the GetAtomHandle function.

UINT GetAtomName(

ATOM  nAtom,	// atom identifying character string
LPTSTR  lpBuffer,	// address of buffer for atom string
int  nSize	// size of buffer
);
Parameters

nAtom

Specifies the local atom that identifies the character string to be retrieved.

lpBuffer

Points to the buffer for the character string.

nSize

Specifies the size, in characters, of the buffer.

Return Value

If the function succeeds, the return value is the length of the string copied to the buffer, in characters, not including the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The string returned for an integer atom (an atom created by the MAKEINTATOM macro) is a null-terminated string in which the first character is a pound sign (#) and the remaining characters represent the unsigned integer originally passed to MAKEINTATOM.

See Also

AddAtom, DeleteAtom, FindAtom, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName, MAKEINTATOM


GetBinaryType

The GetBinaryType function determines whether a file is executable, and if so, what type of executable file it is. That last property determines which subsystem an executable file runs under.

BOOL GetBinaryType (

LPCTSTR  lpApplicationName,	// points to fully qualified path of file to test
LPDWORD  lpBinaryType	// points to variable to receive binary type information
);
Parameters

lpApplicationName

Points to a null-terminated string that contains the fully qualified path of the file whose binary type the function shall determine.

lpBinaryType

Points to a variable to receive information about the executable type of the file specified by lpApplicationName. The function adjusts a set of bit flags in this variable. The following bit flag constants are defined:

Value	Description
SCS_32BIT_BINARY	A Win32-based application
SCS_DOS_BINARY	An MS-DOS − based application
SCS_OS216_BINARY	A 16-bit OS/2-based application
SCS_PIF_BINARY	A PIF file that executes an MS-DOS − based application
SCS_POSIX_BINARY	A POSIX − based application
SCS_WOW_BINARY	A 16-bit Windows-based application
Return Value

If the file is executable, the return value is TRUE. The function sets the variable pointed to by lpBinaryType to indicate the file's executable type.

If the function is not executable, or if the function fails, the return value is FALSE.


GetBitmapBits

The GetBitmapBits function copies the bitmap bits of a specified bitmap into a buffer.

The GetBitmapBits function is not implemented in the Win32 API. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the GetDIBits function.

LONG GetBitmapBits(

HBITMAP  hbmp,	// handle to bitmap
LONG  cbBuffer,	// number of bytes to copy to buffer
LPVOID  lpvBits	// address of buffer for bitmap bits
);
Parameters

hbmp

Identifies the bitmap of interest.

cbBuffer

Specifies the number of bytes to be copied.

lpvBits

Points to a buffer to receive the bitmap bits. This is stored as an array of byte values.

Return Value

If the function succeeds, the return value is the actual number of bytes in the bitmap.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The bits in the destination buffer must be word-aligned. In other words, the buffer must begin at an even address in memory.

See Also

GetDIBits


GetBitmapDimension

The GetBitmapDimension function is not implemented in the Win32 SDK. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the GetBitmapDimensionEx function.


GetBitmapDimensionEx

The GetBitmapDimensionEx function retrieves the dimensions of a bitmap. The retrieved dimensions must have been set by the SetBitmapDimensionEx function. The GetMapDimensionEx function replaces the GetMapDimension function.

BOOL GetBitmapDimensionEx(

HBITMAP  hBitmap,	// handle of bitmap
LPSIZE  lpDimension	// address of structure receiving dimensions
);
Parameters

hBitmap

Identifies the bitmap.

lpDimension

Points to a SIZE structure to receive the bitmap dimensions.

Return Value

If the function was successful, the return value is TRUE.

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

Remarks

The function returns a data structure that contains fields for the height and width of the bitmap. If those dimensions have not yet been set, the structure that is returned will have zeroes in those fields.

See Also

SetBitmapDimensionEx, SIZE


GetBkColor

The GetBkColor function returns the current background color for the specified device context.

COLORREF GetBkColor(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context whose background color is to be returned.

Return Value

If the function succeeds, the return value is a COLORREF value for the current background color.

If the function fails, the return value is CLR_INVALID.

See Also

GetBkMode, SetBkColor


GetBkMode

The GetBkMode function returns the current background mix mode for a specified device context. The background mix mode of a device context affects text, hatched brushes, and pen styles that are not solid lines.

int GetBkMode(

HDC  hdc	// handle to device context of interest
);
Parameters

hdc

Identifies the device context whose background mode is to be returned.

Return Value

If the function succeeds, the return value specifies the current background mix mode, either OPAQUE or TRANSPARENT.

If the function fails, the return value is zero.

See Also

GetBkColor, SetBkMode


GetBoundsRect

The GetBoundsRect function obtains the current accumulated bounding rectangle for a specified device context.

Windows maintains an accumulated bounding rectangle for each application. An application can retrieve and set this rectangle.

UINT GetBoundsRect(

HDC  hdc,	// handle to device context of interest
LPRECT  lprcBounds,	// points to structure to receive bounding rectangle
UINT  flags	// specifies function options
);
Parameters

hdc

Identifies the device context whose bounding rectangle the function will return.

lprcBounds

Points to the RECT structure that will receive the current bounding rectangle. The application's rectangle is returned in logical coordinates, and the Windows rectangle is returned in screen coordinates.

flags

Specifies aspects of how the GetBoundsRect function will operate on a given call. This parameter can be the following value:

Value	Meaning
DCB_RESET	Clears the bounding rectangle after returning it. If this flag is not set, the bounding rectangle will not be cleared.
Return Value

The return value specifies the state of the accumulated bounding rectangle; it can be one of the following values:

Value	Meaning
0	An error occurred. The given device context handle is invalid.
DCB_DISABLE	Boundary accumulation is off.
DCB_ENABLE	Boundary accumulation is on.
DCB_RESET	The bounding rectangle is empty.
DCB_SET	The bounding rectangle is not empty.
Remarks

The DCB_SET value is a combination of the bit values DCB_ACCUMULATE and DCB_RESET. Applications that check the DCB_RESET bit to determine whether the bounding rectangle is empty must also check the DCB_ACCUMULATE bit. The bounding rectangle is empty only if the DCB_RESET bit is 1 and the DCB_ACCUMULATE bit is 0.

See Also

SetBoundsRect


GetBrushOrg

The GetBrushOrg function is not implemented in the Win32 API. This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the GetBrushOrgEx function.


GetBrushOrgEx

The GetBrushOrgEx function retrieves the current brush origin for the specified device context. This function replaces the GetBrushOrg function.

BOOL GetBrushOrgEx(

HDC  hdc,	// handle of device context
LPPOINT  lppt	// address of structure of coordinates
);
Parameters

hdc

Identifies the device context.

lppt

Points to a POINT structure that receives the brush origin, in device coordinates.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A brush is a bitmap that Windows uses to paint the interiors of filled shapes.

The brush origin is a set of coordinates with values between 0 and 7, specifying the location of one pixel in the bitmap. The default brush origin coordinates are (0,0). For horizontal coordinates, the value 0 corresponds to the leftmost column of pixels; the value 7 corresponds to the rightmost column. For vertical coordinates, the value 0 corresponds to the uppermost row of pixels; value 7 corresponds to the lowermost row. When Windows positions the brush at the start of any painting operation, it maps the origin of the brush to the location in the window's client area specified by the brush origin. For example, if the origin is set to (2,3), Windows maps the origin of the brush (0,0) to the location (2,3) on the window's client area.

If an application uses a brush to fill the backgrounds of both a parent and a child window with matching colors, it may be necessary to set the brush origin after painting the parent window but before painting the child window.

See Also

SetBrushOrgEx, POINT


GetCapture

The GetCapture function retrieves the handle of the window (if any) that has captured the mouse. Only one window at a time can capture the mouse; this window receives mouse input whether or not the cursor is within its borders.

HWND GetCapture(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the handle of the capture window associated with the current thread. If no window in the thread has captured the mouse, the return value is NULL.

Remarks

A NULL return value does not mean no other thread or process in the system has captured the mouse; it just means the current thread has not captured the mouse.

See Also

ReleaseCapture, SetCapture


GetCaretBlinkTime

The GetCaretBlinkTime function returns the elapsed time, in milliseconds, required to invert the caret's pixels.

UINT GetCaretBlinkTime(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the blink time, in milliseconds.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

SetCaretBlinkTime


GetCaretPos

The GetCaretPos function copies the caret's position, in client coordinates, to the specified POINT structure.

BOOL GetCaretPos(

LPPOINT  lpPoint	// address of structure to receive coordinates
);
Parameters

lpPoint

Points to the POINT structure that is to receive the client coordinates of the caret.

Return Value

If the function succeeds, the return value is TRUE

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

Remarks

The caret position is always given in the client coordinates of the window that contains the caret.

See Also

SetCaretPos, POINT


GetCharABCWidths

The GetCharABCWidths function retrieves the widths, in logical units, of consecutive characters in a given range from the current TrueType font. This function succeeds only with TrueType fonts.

BOOL GetCharABCWidths(

HDC  hdc,	// handle of device context
UINT  uFirstChar,	// first character in range to query
UINT  uLastChar,	// last character in range to query
LPABC  lpabc	// address of character-width structure
);
Parameters

hdc

Identifies the device context.

uFirstChar

Specifies the first character in the group of consecutive characters from the current font.

uLastChar

Specifies the last character in the group of consecutive characters from the current font.

lpabc

Points to an array of ABC structures that receive the character widths when the function returns. This array must contain at least as many ABC structures as there are characters in the range specified by the uFirstChar and uLastChar parameters.

Return Value

If the function succeeds, the return value is TRUE

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

Remarks

The TrueType rasterizer provides ABC character spacing after a specific point size has been selected. "A" spacing is the distance added to the current position before placing the glyph. "B" spacing is the width of the black part of the glyph. "C" spacing is the distance added to the current position to provide white space to the right of the glyph. The total advanced width is given by A+B+C.

When the GetCharABCWidths function retrieves negative "A" or "C" widths for a character, that character includes underhangs or overhangs.

To convert the ABC widths to font design units, an application should use the value stored in the otmEMSquare member of a OUTLINETEXTMETRIC structure. This value can be retrieved by calling the GetOutlineTextMetrics function.

The ABC widths of the default character are used for characters outside the range of the currently selected font.

To retrieve the widths of characters in non-TrueType fonts, applications should use the GetCharWidth function.

See Also

GetCharWidth, GetOutlineTextMetrics, OUTLINETEXTMETRIC, ABC


GetCharABCWidthsFloat

The GetCharABCWidthsFloat function retrieves the widths, in logical units, of consecutive characters in a specified range from the current font.

BOOL GetCharABCWidthsFloat(

HDC  hdc,	// handle of device context
UINT  iFirstChar,	// first character in range to query
UINT  iLastChar,	// last character in range to query
LPABCFLOAT  lpABCF	// address of character-width structure
);
Parameters

hdc

Identifies the device context.

iFirstChar

Specifies the code point of the first character in the group of consecutive characters where the ABC widths are sought.

iLastChar

Specifies the code point of the last character in the group of consecutive characters where the ABC widths are sought. This range is inclusive. An error is returned if the specified last character precedes the specified first character.

lpABCF

Points to an application-defined buffer with an array of ABCFLOAT structures to receive the character widths when the function returns.

Return Value

If the function succeeds, the return value is TRUE

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

Remarks

Unlike the GetCharABCWidths function that returns widths only for TrueType fonts, the GetCharABCWidthsFloat function retrieves widths for any font. The widths returned by this function are in the IEEE floating-point format.

If the current world-to-device transformation is not identified, the returned widths may be noninteger values, even if the corresponding values in the device space are integers.

"A" spacing is the distance added to the current position before placing the glyph. "B" spacing is the width of the black part of the glyph. "C" spacing is the distance added to the current position to provide white space to the right of the glyph. The total advanced width is given by A+B+C.

The ABC spaces are measured along the character base line of the selected font.

The ABC widths of the default character are used for characters outside the range of the currently selected font.

See Also

ABCFLOAT, GetCharABCWidths, GetCharWidth, GetCharWidthFloat


GetCharacterPlacement  (preliminaryWindows 95)
GetCharacterPlacement  (preliminary−Windows 95)

The GetCharacterPlacement function retrieves information about a character string, such as character widths, caret positioning, ordering within the string, and glyph rendering. The type of information returned depends on the dwFlags parameter and is based on the currently selected font in the given display context. The function copies the information to the given GCP_RESULTS structure or to one or more arrays specified by the structure.

DWORD GetCharacterPlacement(

HDC  hdc,	// handle of device context
LPCTSTR  lpString,	// address of string
int  nCount,	// number of characters in string
int  nMaxExtent,	// maximum extent for displayed string
LPGCP_RESULTS  *lpResults,	// address of buffer for placement result
DWORD  dwFlags	// placement flags
);
Parameters

hdc

Identifies the device context.

lpString

Points to the character string to process.

nCount

Specifies the number of characters in the string.

nMaxExtent

Specifies the maximum extent (in logical units) to which the string is processed. Characters that, if processed, would exceed this extent are ignored. Computations for any required ordering or glyph arrays apply only to the included characters. This parameter is used only if the GCP_MAXEXTENT or GCP_JUSTIFY value is given in the dwFlags parameter.

lpResults

Points to a GCP_RESULTS structure that receives the result of the function.

dwFlags

Specifies how to process the string into the required arrays. This parameter can be one of the following values:

Value	Meaning
GCP_CLASSIN	Specifies that the lpClass array contains preset classifications for characters. The classifications may be the same as on output. If the particular classification for a character is not known, the corresponding location in the array must be set to zero. for more information about the classifications, see GCP_RESULTS.
GCP_DIACRITIC	Specifies that diacritics in the string are handled appropriately. If this value is not set, diacritics are treated as zero width characters. Use GetFontLanguageInfo to determine whether a font supports diacritics.
GCP_GLYPHSHAPE	Specifies that some or all characters in the string are to be displayed using shapes other than the standard shapes defined in the currently selected font for the current code page. Some languages, such as Arabic, cannot support glyph creation unless this value is given. As a general rule, if GetFontLanguageInfo returns this value for a string, this value must be used with GetCharacterPlacement.
GCP_JUSTIFY	Adjusts the extents in the lpDx array so that the string length is the same as nMaxExtent. GCP_JUSTIFY may only be used in conjunction with GCP_MAXEXTENT.
GCP_JUSTIFYIN	Specifies that the lpDx array contains justification weights on input. For non-Arabic fonts, a justification weight can be either 0 or 1, where 1 indicates that the width of the given character can be padded for justification. For Arabic fonts, a justification weight can be in the range 0 to 8.
GCP_KASHIDA	Use Kashidas instead of adjusted extents to modify the length of the string so that it is equal to the value given by nMaxExtent. In the lpDx array, a Kashida is indicated by a negative justification index. GCP_KASHIDA may only be used in conjunction with GCP_JUSTIFY and only if the font (and language) support Kashidas. Use GetFontLanguageInfo to determine whether the current font supports Kashidas.
GCP_LIGATE	Use ligations wherever characters ligate. If the GCP_REORDER value is usually required for the character set but is not given, the output will be meaningless. Use getFontLanguageInfo to determine whether the current font supports ligation. If it does and a specific maximum is required for the number of characters which will ligate, set the number in the first element of the lpGlyphs array. If normal ligation is required, set this value to zero. If GCP_LIGATE is not given, no ligation will take place.
GCP_MAXEXTENT	Compute extents of the string only as long as the resulting extent, in logical units, does not exceed the values given by the nMaxExtent parameter.
GCP_NEUTRALOVERRIDE	Semitic languages only. Override the normal handling of neutrals and treat them as strong characters which match the strings reading order.
GCP_NUMERICOVERRIDE	Semitic languages only. Override the normal handling of numerics and treat them as strong characters which match the strings reading order.
GCP_NUMERICSLATIN	Arabic/Thai only. Use standard latin glyphs for numbers and override the system default.
GCP_NUMERICSLOCAL	Arabic/Thai only. Use local glyphs for numeric characters and override the system default.
GCP_REORDER	Reorder the string. Use for fonts that are neither SBCS nor left-to-right reading order. If this value is not given, the string is assumed to be in display order already.  If this flag is set for Semitic languages and the lpClass array is used, the first two elements of the array are used to specify the reading order beyond the bounds of the string. GCP_CLASS_PREBOUNDRTL and GCP_CLASS_PREBOUNDLTR can be used to set the order. If no preset order is required, set the values to zero. These values can be combined with other values if theGCPCLASSIN flag is set. If the GCP_REORDER value is not given, the lpString parameter is taken to be visual ordered for languages where this is used, and the lpOutString and lpOrder fields are ignored. Use GetFontLanguageInfo to determine whether the current font supports reordering.
GCP_SYMSWAPOFF	Semitic languages only. Specifies that swappable characters are not reset. For example, in a right-to-left string, the '(' and ')' are not reversed.
GCP_USEKERNING	Use kerning pairs in the font (if any) when creating the widths arrays. Use GetFontLanguageInfo to determine whether the current font supports kerning pairs.
It is recommended that an application use the GetFontLanguageInfo function to determine whether the GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE, and GCP_KASHIDA values are valid for the currently selected font. If not valid, GetCharacterPlacement ignores the value.

The GCP_NODIACRITICS value is no longer defined and should not be used.

Return Value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero.

Remarks

GetCharacterPlacement ensures that an application can correctly process text regardless of the international setting and type of fonts available. Applications use this function prior to using the ExtTextOut function and in place the GetTextExtentPoint32 function (and occasionally in place of the GetCharWidth32 and GetCharABCWidths functions).

Using GetCharacterPlacement to retrieve intercharacter spacing and index arrays is not always necessary unless justification and/or kerning are required. For non-Latin fonts, applications can improve the speed at which the ExtTextOut function renders text by using GetCharacterPlacement to retrieve the intercharacter spacing and index arrays before calling ExtTextOut. This is especially useful when rendering the same text repeatedly or when using intercharacter spacing to position the caret. If the lpGlyphs output array is used in the call to ExtTextOut, the ETO_GLYPH_INDEX flag must be set.

GetCharacterPlacement checks the lpOrder, lpDx, lpCaretPos, and lpGlyphs members of the GCP_RESULTS structure and fills the corresponding arrays if these members are not set to NULL. If GetCharacterPlacement cannot fill an array, it sets the corresponding member to NULL. To ensure retrieval of valid information, the application is responsible for setting the member to a valid address before calling the function and for checking the value of the member after the call. If the GCP_JUSTIFY or GCP_USEKERNING values are given, the lpDx and/or lpCaretPos members must have valid addresses. Also, the lpDx member must have a valid address if GCP_JUSTIFYIN is given.

When computing justification, if the trailing characters in the string are spaces, the function reduces the length of the string and removes the spaces prior to computing the justification. If the array consists of only spaces, the function returns an error.

See Also

ExtTextOut, GCP_RESULTS, GetCharABCWidths, GetCharWidth32, GetFontLanguageInfo, GetTextExtentPoint32


GetCharWidth

The GetCharWidth function retrieves the widths, in logical coordinates, of consecutive characters in a specified range from the current font.

GetCharWidth is maintained for compatibility with 16-bit versions of Windows. Win32-based applications should call the GetCharWidth32 function, which provides more accurate results.

BOOL GetCharWidth(

HDC  hdc,	// handle of device context
UINT  iFirstChar,	// first character in range to query
UINT  iLastChar,	// last character in range to query
LPINT  lpBuffer	// address of buffer for widths
);
Parameters

hdc

Identifies the device context.

iFirstChar

Specifies the first character in the group of consecutive characters.

iLastChar

Specifies the last character in the group of consecutive characters, which must not precede the specified first character.

lpBuffer

Points to a buffer to receive the widths.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The range is inclusive; that is, the returned widths include the widths of the characters specified by the iFirstChar and iLastChar parameters.

If a character does not exist in the current font, it is assigned the width of the default character.

See Also

GetCharABCWidths, GetCharABCWidthsFloat, GetCharWidth32, GetCharWidthFloat


GetCharWidth32

The GetCharWidth32 function retrieves the widths, in logical coordinates, of consecutive characters in a specified range from the current font. This function supersedes the GetCharWidth function.

BOOL GetCharWidth32(

HDC  hdc,	// handle of device context
UINT  iFirstChar,	// first character in range to query
UINT  iLastChar,	// last character in range to query
LPINT  lpBuffer	// address of buffer for widths
);
Parameters

hdc

Identifies the device context.

iFirstChar

Specifies the first character in the group of consecutive characters.

iLastChar

Specifies the last character in the group of consecutive characters, which must not precede the specified first character.

lpBuffer

Points to a buffer to receive the widths.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The range is inclusive; that is, the returned widths include the widths of the characters specified by the iFirstChar and iLastChar parameters.

If a character does not exist in the current font, it is assigned the width of the default character.

See Also

GetCharABCWidths, GetCharABCWidthsFloat, GetCharWidth, GetCharWidthFloat


GetCharWidthFloat

The GetCharWidthFloat function retrieves the fractional widths of consecutive characters in a specified range from the current font.

BOOL GetCharWidthFloat(

HDC  hdc,	// handle of device context
UINT  iFirstChar,	// first-character code point
UINT  iLastChar,	// last-character code point
PFLOAT  pxBuffer	// address of buffer that receives width-values
);
Parameters

hdc

Identifies the device context.

iFirstChar

Specifies the code point of the first character in the group of consecutive characters.

iLastChar

Specifies the code point of the last character in the group of consecutive characters.

pxBuffer

Points to a buffer to receive the character widths.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The returned widths are in the 32-bit IEEE floating-point format. (The widths are measured along the base line of the characters.)

If the iFirstChar parameter identifies the letter a and the iLastChar parameter identifies the letter z, GetCharWidthFloat retrieves the widths of all lowercase characters.

If a character does not exist in the current font, it is assigned the width of the default character.

See Also

GetCharABCWidths, GetCharABCWidthsFloat, GetCharWidth32


GetClassInfo

The GetClassInfo function retrieves information about a window class.

BOOL GetClassInfo(

HINSTANCE  hInstance,	// handle of application instance
LPCTSTR  lpClassName,	// address of class name string
LPWNDCLASS  lpWndClass	// address of structure for class data
);
Parameters

hInstance

Identifies the instance of the application that created the class. To retrieve information about classes defined by Windows (such as buttons or list boxes), set this parameter to NULL.

lpClassName

Points to a null-terminated string containing the class name. The name must be that of a preregistered class or a class registered by a previous call to the RegisterClass function. Alternatively, this parameter can be an integer atom. If so, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpClassName; the high-order word must be zero.

lpWndClass

Points to a WNDCLASS structure that receives the information about the class.

Return Value

If the function finds a matching class and successfully copies the data, the return value is TRUE.

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

See Also

GetClassLong, GetClassName, GetClassWord, GlobalAddAtom, RegisterClass, WNDCLASS


GetClassInfoEx  (preliminaryWindows 95)
GetClassInfoEx

The GetClassInfoEx function retrieves information about a window class, including the handle of the small icon associated with the window class. GetClassInfo does not retrieve the handle of the small icon.

BOOL GetClassInfoEx(

HINSTANCE  hinst,	// handle of application instance
LPCTSTR  lpszClass,	// address of class name string
LPWNDCLASSEX  lpwcx,	// address of structure for class data
);
Parameters

hinst

Identifies the instance of the application that created the class. To retrieve information about classes defined by Windows (such as buttons or list boxes), set this parameter to NULL.

lpszClass

Points to a null-terminated string containing the class name. The name must be that of a preregistered class or a class registered by a previous call to the RegisterClass function. Alternatively, this parameter can be an integer atom. If this parameter is an integer atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value less than 0xC000, must be in the low-order word of lpszClass; the high-order word must be zero.

lpwcx

Points to a WNDCLASSEX structure that receives the information about the class.

Windows NT: With Windows NT the hIconSm member of the WNDCLASSEX structure is always NULL.

Return Value

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, call GetLastError.

See Also

GetClassLong, GetClassName, GetClassWord, GlobalAddAtom, RegisterClassEx


GetClassLong

The GetClassLong function retrieves the specified 32-bit (long) value from the WNDCLASS structure associated with the specified window.

DWORD GetClassLong(

HWND  hWnd,	// handle of window
int  nIndex	// offset of value to retrieve
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the 32-bit value to retrieve. To retrieve a 32-bit value from the extra class memory, specify the positive, zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra class memory, minus four; for example, if you specified 12 or more bytes of extra class memory, a value of 8 would be an index to the third 32-bit integer. To retrieve any other value from the WNDCLASS structure, specify one of the following values:

Value	Action
GCW_ATOM	Retrieves an ATOM value that uniquely identifies the window class. This is the same atom that the RegisterClass function returns.
GCL_CBCLSEXTRA	Retrieves the size, in bytes, of the extra memory associated with the class.
GCL_CBWNDEXTRA	Retrieves the size, in bytes, of the extra window memory associated with each window in the class. For information on how to access this memory, see  GetWindowLong and GetWindowWord .
GCL_HBRBACKGROUND	Retrieves the handle of the background brush associated with the class.
GCL_HCURSOR	Retrieves the handle of the cursor associated with the class.
GCL_HICON	Retrieves the handle of the icon associated with the class.
GCL_HICONSM	Windows 95: Retrieves the handle of the small icon associated with the class. Windows NT: This constant is not valid for Windows NT.
GCL_HMODULE	Retrieves the handle of the module that registered the class.
GCL_MENUNAME	Retrieves the address of the menu name string. The string identifies the menu resource associated with the class.
GCL_STYLE	Retrieves the window-class style bits.
GCL_WNDPROC	Retrieves the address of the window procedure associated with the class.
Return Value

If the function succeeds, the return value is the requested 32-bit value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

See Also

GetClassWord, GetWindowLong, GetWindowWord, RegisterClass, SetClassLong, SetClassWord, WNDCLASS


GetClassName

The GetClassName function retrieves the name of the class to which the specified window belongs.

int GetClassName(

HWND  hWnd,	// handle of window
LPTSTR  lpClassName,	// address of buffer for class name
int  nMaxCount	// size of buffer, in characters
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

lpClassName

Points to the buffer that is to receive the class name string.

nMaxCount

Specifies the length, in characters, of the buffer pointed to by the lpClassName parameter. The class name string is truncated if it is longer than the buffer.

Return Value

If the function succeeds, the return value is the number of characters copied to the specified buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

FindWindow, GetClassInfo, GetClassLong, GetClassWord


GetClassWord

The GetClassWord function retrieves the 16-bit (word) value at the specified offset into the extra class memory for the window class to which the specified window belongs.

WORD GetClassWord(

HWND  hWnd,	// handle of window
int  nIndex	// offset of value to retrieve
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of class memory, minus two; for example, if you specified 10 or more bytes of extra class memory, a value of eight would be an index to the fifth 16-bit integer. There is an additional valid value:

Value	Action
GCW_ATOM	Retrieves an ATOM value that uniquely identifies the window class. This is the same atom that the RegisterClass function returns.
GCW_HICONSM	Windows 95: Retrieves the handle of the small icon associated with the window. Windows NT: This constant is not valid for Windows NT.
Return Value

If the function succeeds, the return value is the requested 16-bit value.

If the function fails, the return value is otherwise, it is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

Other than GCW_ATOM and GCW_HICONSM, the GCW_ values are obsolete in the Win32 API. You must use the GetClassLong function to retrieve the class values of a window.

See Also

GetClassLong, RegisterClass, SetClassLong, SetClassWord, WNDCLASS


GetClientRect

The GetClientRect function retrieves the coordinates of a window's client area. The client coordinates specify the upper-left and lower-right corners of the client area. Because client coordinates are relative to the upper-left corner of a window's client area, the coordinates of the upper-left corner are (0,0).

BOOL GetClientRect(

HWND  hWnd,	// handle of window
LPRECT  lpRect	// address of structure for client coordinates
);
Parameters

hWnd

Identifies the window whose client coordinates are to be retrieved.

lpRect

Points to a RECT structure that receives the client coordinates. The left and top members are zero. The right and bottom members contain the width and height of the window.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetWindowRect, RECT


GetClipboardData

The GetClipboardData function retrieves data from the clipboard in a specified format. The clipboard must have been opened previously.

HANDLE GetClipboardData(

UINT  uFormat	// clipboard format
);
Parameters

uFormat

Specifies a clipboard format. For a description of the clipboard formats, see the SetClipboardData function.

Return Value

If the function succeeds, the return value is the handle of a clipboard object in the specified format.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

An application can enumerate the available formats in advance by using the EnumClipboardFormats function.

The clipboard controls the handle that the GetClipboardData function returns, not the application. The application should copy the data immediately. The application cannot rely on being able to make long-term use of the handle. The application must not free the handle nor leave it locked.

The operating system performs implicit data format conversions between certain clipboard formats when an application calls the GetClipboardData function. For example, if the CF_OEMTEXT format is on the clipboard, a window can retrieve data in the CF_TEXT format. The format on the clipboard is converted to the requested format on demand. The following table shows the clipboard data type conversions that are available. Note that some of these automatic type conversions are not available on all platforms.

Clipboard Format	Conversion Format	Platform Support
CF_BITMAP	CF_DIB	Windows 95
CF_DIB	CF_BITMAP	Windows 95
CF_DIB	CF_PALETTE	Windows 95
CF_ENHMETAFILE	CF_METAFILEPICT	Windows 95, Windows NT
CF_METAFILEPICT	CF_ENHMETAFILE	Windows 95, Windows NT
CF_OEMTEXT	CF_TEXT	Windows 95, Windows NT
CF_OEMTEXT	CF_UNICODETEXT	Windows NT
CF_TEXT	CF_OEMTEXT	Windows 95, Windows NT
CF_TEXT	CF_UNICODETEXT	Windows NT
CF_UNICODETEXT	CF_OEMTEXT	Windows NT
CF_UNICODETEXT	CF_TEXT	Windows NT
If the operating system provides an automatic type conversion for a particular clipboard format, there is no advantage to placing the conversion format(s) on the clipboard.

If the system provides an automatic type conversion for a particular clipboard format, and you call EnumClipboardFormats to enumerate the clipboard data formats, the operating system first enumerates the format that is on the clipboard, followed by the formats to which it can be converted.

If the clipboard contains data in the CF_PALETTE format, the application should use the SelectPalette and RealizePalette functions to realize any other data in the clipboard against that logical palette.

See SetClipboardData for further information on specific clipboard data formats.

See Also

EnumClipboardFormats, SetClipboardData, RealizePalette, SelectPalette


GetClipboardFormatName

The GetClipboardFormatName function retrieves from the clipboard the name of the specified registered format. The function copies the name to the specified buffer.

int GetClipboardFormatName(

UINT  format,	// clipboard format to retrieve
LPTSTR  lpszFormatName,	// address of buffer for name
int  cchMaxCount	// length of name string in characters
);
Parameters

format

Specifies the type of format to be retrieved. This parameter must not specify any of the predefined clipboard formats.

lpszFormatName

Points to the buffer that is to receive the format name.

cchMaxCount

Specifies the maximum length, in characters, of the string to be copied to the buffer. If the name exceeds this limit, it is truncated.

Return Value

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer.

If the function fails, the return value is zero, indicating that the requested format does not exist or is predefined. To get extended error information, call GetLastError.

See Also

EnumClipboardFormats, RegisterClipboardFormat


GetClipboardOwner

The GetClipboardOwner function retrieves the window handle of the current owner of the clipboard.

HWND GetClipboardOwner(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the handle of the window that owns the clipboard.

If the clipboard is not owned, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The clipboard can still contain data even if the clipboard is not currently owned.

In general, the clipboard owner is the window that last placed data in clipboard. The EmptyClipboard function assigns clipboard ownership.

See Also

EmptyClipboard, GetClipboardViewer


GetClipboardViewer

The GetClipboardViewer function retrieves the handle of the first window in the clipboard viewer chain.

HWND GetClipboardViewer(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the handle of the first window in the clipboard viewer chain.

If there is no clipboard viewer, the return value is NULL. To get extended error information, call GetLastError.

See Also

GetClipboardOwner, SetClipboardViewer


GetClipBox

The GetClipBox function retrieves the dimensions of the tightest bounding rectangle that can be drawn around the current visible area on the device. The visible area is defined by the current clipping region or clip path, as well as any overlapping windows.

int GetClipBox(

HDC  hdc,	// handle of the device context
LPRECT  lprc	// address of structure with rectangle
);
Parameters

hdc

Identifies the device context.

lprc

Points to a RECT structure that is to receive the rectangle dimensions.

Return Value

If the function succeeds, the return value specifies the clipping box's complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred.
See Also

RECT


GetClipCursor

The GetClipCursor function retrieves the screen coordinates of the rectangular area to which the cursor is confined.

BOOL GetClipCursor(

LPRECT  lpRect	// address of structure for rectangle
);
Parameters

lpRect

Points to a RECT structure that receives the screen coordinates of the confining rectangle. The structure receives the dimensions of the screen if the cursor is not confined to a rectangle.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The cursor is a shared resource. If an application confines the cursor with the ClipCursor function, it must later release the cursor by using ClipCursor before relinquishing control to another application.

The calling process must have WINSTA_READATTRIBUTES access to the window station.

See Also

ClipCursor, GetCursorPos, RECT


GetClipRgn

The GetClipRgn function retrieves a handle identifying the current application-defined clipping region for the specified device context.

int GetClipRgn(

HDC  hdc,	// handle of device context
HRGN  hrgn	// handle of region
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies an existing region before the function is called. After the function returns, this parameter identifies a copy of the current clipping region.

Return Value

If the function succeeds and there is no clipping region for the given device context, the return value is zero. If the function succeeds and there is a clipping region for the given device context, the return value is 1. If an error occurs, the return value is − 1.

Remarks

An application-defined clipping region is a clipping region identified by the SelectClipRgn function. It is not a clipping region created when the application calls the BeginPaint function.

If the function succeeds, the hrgn parameter identifies a copy of the current clipping region. Subsequent changes to this copy will not affect the current clipping region.

See Also

BeginPaint, SelectClipRgn


GetCodeHandle

The GetCodeHandle function is not implemented in the Win32 API. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GetCodeInfo

The GetCodeInfo function is not implemented in the WIN32 SDK. This function is included for compatability with 16-bit versions of Windows.


GetColorAdjustment

The GetColorAdjustment function retrieves the color adjustment values for the specified device context.

BOOL GetColorAdjustment(

HDC  hdc,	// handle of device context
LPCOLORADJUSTMENT  lpca	// address of COLORADJUSTMENT structure
);
Parameters

hdc

Identifies the device context.

lpca

Points to a COLORADJUSTMENT structure that receives the color adjustment values.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

SetColorAdjustment, COLORADJUSTMENT


GetColorSpace  (preliminaryWindows 95)
GetColorSpace  (preliminary−Windows 95)

The GetColorSpace function retrieves the current handle to the logical color space from the specified device context.

HANDLE GetColorSpace(

HDC  hdc
);
Parameters

hdc

Handle to a device context.

Return Value

If the function succeeds, the return value is the current handle to the logical color space.

If the function fails, the return value is NULL.


GetCommandLine

The GetCommandLine function returns a pointer to the command-line string for the current process.

LPTSTR GetCommandLine(VOID)

Parameters

This function has no parameters.

Return Value

The return value is a pointer to the command-line string for the current process.

Remarks

Non-Unicode console processes written in C can use the argc and argv arguments to access the command-line arguments. The parameters of the command-line string, excluding the program name, are also available to such non-Unicode applications as a parameter of the WinMain function. The reason for the Unicode exclusion from these options is that WinMain, argc, and argv use the LPSTR data type for parameters, not the LPTSTR datatype.

See Also

CreateProcess, WinMain


GetCommConfig  (preliminaryWindows 95)
GetCommConfig  (preliminary−Windows 95)

The GetCommConfig function gets the current configuration of a communications device.

BOOL GetCommConfig(

HANDLE hCommDev,	// handle of communications service
LPCOMMCONFIG lpCC,	// address of comm.configuration structure
LPDWORD lpdwSize	// address of size of buffer
);
Parameters

hCommDev

Identifies the open communications device.

lpCC

Points to the buffer that receives the COMMCONFIG structure.

lpdwSize

Points to a 32-bit variable that specifies the size, in bytes, of the buffer pointed to by lpCC. When the function returns, the variable contains the number of bytes copied if the function succeeds, or the number of bytes required if the buffer was too small.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

Remarks

An application can determine the maximum size of a device's configuration structure by calling the GetCommProperties function.

See Also

COMMCONFIG, GetCommProperties


GetCommMask

The GetCommMask function retrieves the value of the event mask for a specified communications device.

BOOL GetCommMask(

HANDLE  hFile,	// handle of communications device
LPDWORD  lpEvtMask	// address of variable to get event mask
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpEvtMask

Points to the 32-bit variable to be filled with a mask of events that are currently enabled. This parameter can be one or more of the following values:

Value	Meaning
EV_BREAK	A break was detected on input.
EV_CTS	The CTS (clear-to-send) signal changed state.
EV_DSR	The DSR (data-set-ready) signal changed state.
EV_ERR	A line-status error occurred. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY.
EV_EVENT1	An event of the first provider-specific type occured.
EV_EVENT2	An event of the second provider-specific type occured.
EV_PERR	A printer error occured.
EV_RING	A ring indicator was detected.
EV_RLSD	The RLSD (receive-line-signal-detect) signal changed state.
EV_RX80FULL	The receive buffer is 80 percent full.
EV_RXCHAR	A character was received and placed in the input buffer.
EV_RXFLAG	The event character was received and placed in the input buffer. The event character is specified in the device's DCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY	The last character in the output buffer was sent.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The GetCommMask function uses a 32-bit mask variable to indicate the set of events that can be monitored for a particular communications resource. A handle to the communications resource can be specified in a call to the WaitCommEvent function, which waits for one of the events to occur. To modify the event mask of a communications resource, use the SetCommMask function.

See Also

CreateFile, DCB, SetCommMask, WaitCommEvent,


GetCommModemStatus

The GetCommModemStatus function retrieves modem control-register values.

BOOL GetCommModemStatus(

HANDLE  hFile,	// handle of communications device
LPDWORD  lpModemStat	// address of control-register values
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpModemStat

Points to a 32-bit variable that specifies the current state of the modem control-register values. This parameter can be a combination of the following values:

Value	Meaning
MS_CTS_ON	The CTS (clear-to-send) signal is on.
MS_DSR_ON	The DSR (data-set-ready) signal is on.
MS_RING_ON	The ring indicator signal is on.
MS_RLSD_ON	The RLSD (receive-line-signal-detect) signal is on.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The GetCommModemStatus function is useful when you are using the WaitCommEvent function to monitor the CTS, RLSD, DSR, or ring indicator signals. To detect when these signals change state, use WaitCommEvent and then use GetCommModemStatus to determine the state after a change occurs.

The function fails if the hardware does not support the control-register values.

See Also

CreateFile, WaitCommEvent


GetCommProperties

The GetCommProperties function fills a buffer with information about the communications properties for a specified communications device.

BOOL GetCommProperties(

HANDLE  hFile,	// handle of communications device
LPCOMMPROP  lpCommProp	// address of communications properties structure
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpCommProp

Points to a COMMPROP structure in which the communications properties information is returned. This information can be used in subsequent calls to the SetCommState, SetCommTimeouts, or SetupComm function to configure the communications device.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The GetCommProperties function returns information from a device driver about the configuration settings that are supported by the driver.

See Also

COMMPROP, CreateFile, SetCommState, SetCommTimeouts, SetupComm


GetCommState

The GetCommState function fills in a device-control block (a DCB structure) with the current control settings for a specified communications device.

BOOL GetCommState(

HANDLE  hFile,	// handle of communications device
LPDCB  lpDCB	// address of device-control block structure
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpDCB

Points to the DCB structure in which the control settings information is returned.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateFile, DCB, SetCommState


GetCommTimeouts

The GetCommTimeouts function retrieves the time-out parameters for all read and write operations on a specified communications device.

BOOL GetCommTimeouts(

HANDLE  hFile,	// handle of communications device
LPCOMMTIMEOUTS  lpCommTimeouts	// address of comm. time-outs structure
);
Parameters

hFile

Identifies the communications device. The CreateFile function returns this handle.

lpCommTimeouts

Points to a COMMTIMEOUTS structure in which the time-out information is returned.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

For more information about time-out values for communications devices, see the SetCommTimeouts function.

See Also

CreateFile, COMMTIMEOUTS, SetCommTimeouts


GetCompressedFileSize

The GetCompressedFileSize function obtains the compressed size, in bytes, of a specified file.

The GetCompressedFileSize function obtains the actual number of bytes of disk storage used to store a specified file. If the file is located on a volume that supports compression, and the file is compressed, the value obtained is the compressed size of the specified file. If the file is not located on a volume that supports compression, or if the file is not compressed, the value obtained is the actual file size, the same as the value returned by a call to GetFileSize.

DWORD GetCompressedFileSize(

LPCTSTR  lpFileName,	// pointer to name of file
LPDWORD  lpFileSizeHigh	// pointer to DWORD to receive high-order doubleword of file size
);
Parameters

lpFileName

Pointer to a null-terminated string that specifies the name of the file.

lpFileSizeHigh

Pointer to a DWORD variable that the function sets to the high-order doubleword of the compressed file size. The function's return value is the low-order doubleword of the compressed file size.

This parameter can be NULL if the high-order doubleword of the compressed file size is not needed. Files less than 4 gigabytes in size do not need the high-order doubleword.

Return Value

If the function succeeds, the return value is the low-order doubleword of the actual number of bytes of disk storage used to store the specified file, and if lpFileSizeHigh is non-NULL, the function puts the high-order doubleword of that actual value into the DWORD pointed to by that parameter. This is the compressed file size for compressed files, the actual file size for noncompressed files.

If the function fails, and lpFileSizeHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

If the function fails, and lpFileSizeHigh is non-NULL, the return value is 0xFFFFFFFF, and GetLastError returns a value other than NO_ERROR.

Remarks

Calling the GetCompressedFileSize function with the name of a nonseeking device, such as a pipe or a communications device, has no meaning.

Note that if the return value is 0xFFFFFFFF and lpFileSizeHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed.

An application can determine whether a volume is compressed by calling GetVolumeInformation, then checking the status of the FS_VOL_IS_COMPRESSED flag in the DWORD pointed to by that function's lpFileSystemFlags parameter.

An application can determine whether a file is compressed by implementing the following pseudocode:

call GetVolumeInformation on the file's volume

if the file's volume is compressed

call GetCompressedFileSize on the file

call GetFileSize on the file

if the sizes don't match

the file is compressed

See Also

GetFileSize, GetVolumeInformation


GetComputerName

The GetComputerName function retrieves the computer name of the current system. This name is established at system startup, when it is initialized from the registry.

BOOL GetComputerName(

LPTSTR  lpBuffer,	// address of name buffer
LPDWORD  nSize	// address of size of name buffer
);
Parameters

lpBuffer

Points to a buffer to receive the null-terminated character string containing the computer name.

nSize

Points to a variable that specifies the maximum size, in characters, of the buffer. This value should be large enough to contain MAX_COMPUTERNAME_LENGTH + 1 characters.

Return Value

If the function succeeds, the return value is TRUE and the variable at nSize 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, call GetLastError.

See Also

SetComputerName


GetConsoleCP

Windows NT: The GetConsoleCP function returns the identity of the input code page used by the console associated with the calling process. A console uses its input code page to translate keyboard input into the corresponding character value.

Windows 95: On Japanese and Korean implementations of Windows 95, the GetConsoleCP function returns the VM code page, because the OEM code page can be either 437 or DBCS. On all other implementations of Windows 95, the GetConsoleCP function returns the OEM code page.

UINT GetConsoleCP(VOID)

Parameters

This function has no parameters.

Return Value

The return value is a code that identifies the code page.

Remarks

A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages.

To set a console's input code page, use the SetConsoleCP function. To set and query a console's output code page, use the SetConsoleOutputCP and GetConsoleOutputCP functions.

See Also

GetConsoleOutputCP, SetConsoleCP, SetConsoleOutputCP


GetConsoleCursorInfo

The GetConsoleCursorInfo function retrieves information about the size and visibility of the cursor for the specified console screen buffer.

BOOL GetConsoleCursorInfo(

HANDLE  hConsoleOutput,	// handle of console screen buffer
PCONSOLE_CURSOR_INFO  lpConsoleCursorInfo	// address of cursor information
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_READ access.

lpConsoleCursorInfo

Points to a CONSOLE_CURSOR_INFO structure in which information about the console's cursor is returned.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CONSOLE_CURSOR_INFO, SetConsoleCursorInfo


GetConsoleMode

The GetConsoleMode function reports the current input mode of a console's input buffer or the current output mode of a console screen buffer.

BOOL GetConsoleMode(

HANDLE  hConsoleHandle,	// handle of console input or screen buffer
LPDWORD  lpMode	// current mode flags
);
Parameters

hConsoleHandle

Identifies a console input buffer or a screen buffer. The handle must have GENERIC_READ access.

lpMode

Points to a 32-bit variable that indicates the current mode of the specified buffer.

If the hConsoleHandle parameter is an input handle, the mode can be a combination of the following values. When a console is created, all input modes except ENABLE_WINDOW_INPUT are enabled by default.

Value	Meaning
ENABLE_LINE_INPUT	The ReadFile or ReadConsole function returns only when a carriage return character is read. If this mode is disabled, the functions return when one or more characters are available.
ENABLE_ECHO_INPUT	Characters read by the ReadFile or ReadConsole function are written to the active screen buffer as they are read. This mode can be used only if the ENABLE_LINE_INPUT mode is also enabled.
ENABLE_PROCESSED_INPUT	CTRL+C is processed by the system and is not placed in the input buffer. If the input buffer is being read by ReadFile or ReadConsole, other control keys are processed by the system and are not returned in the ReadFile or ReadConsole buffer. If the ENABLE_LINE_INPUT mode is also enabled, backspace, carriage return, and linefeed characters are handled by the system.
ENABLE_WINDOW_INPUT	User interactions that change the size of the console screen buffer are reported in the console's input buffer. Information about these events can be read from the input buffer by applications using the ReadConsoleInput function, but not by those using ReadFile or ReadConsole.
ENABLE_MOUSE_INPUT	If the mouse pointer is within the borders of the console window and the window has the keyboard focus, mouse events generated by mouse movement and button presses are placed in the input buffer. These events are discarded by ReadFile or ReadConsole, even when this mode is enabled.
If the hConsoleHandle parameter is a screen buffer handle, the mode can be a combination of the following values. When a screen buffer is created, both output modes are enabled by default.

Value	Meaning
ENABLE_PROCESSED_OUTPUT	Characters written by the WriteFile or WriteConsole function or echoed by the ReadFile or ReadConsole function are parsed for ASCII control sequences, and the correct action is performed. Backspace, tab, bell, carriage return, and linefeed characters are processed.
ENABLE_WRAP_AT_EOL_OUTPUT	When writing with WriteFile or WriteConsole or echoing with ReadFile or ReadConsole, the cursor moves to the beginning of the next row when it reaches the end of the current row. This causes the rows displayed in the console window to scroll up automatically when the cursor advances beyond the last row in the window. It also causes the contents of the screen buffer to scroll up (discarding the top row of the screen buffer) when the cursor advances beyond the last row in the screen buffer. If this mode is disabled, the last character in the row is overwritten with any subsequent characters.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A console consists of an input buffer and one or more screen buffers. The mode of a console buffer determines how the console behaves during input or output (I/O) operations. One set of flag constants is used with input handles, and another set is used with screen buffer (output) handles. Setting the output modes of one screen buffer does not affect the output modes of other screen buffers.

The ENABLE_LINE_INPUT and ENABLE_ECHO_INPUT modes only affect processes that use ReadFile or ReadConsole to read from the console's input buffer. Similarly, the ENABLE_PROCESSED_INPUT mode primarily affects ReadFile and ReadConsole users, except that it also determines whether CTRL+C input is reported in the input buffer (to be read by the ReadConsoleInput function) or is passed to a function defined by the application.

The ENABLE_WINDOW_INPUT and ENABLE_MOUSE_INPUT modes determine whether user interactions involving window resizing and mouse actions are reported in the input buffer or discarded. These events can be read by ReadConsoleInput, but they are always filtered by ReadFile and ReadConsole.

The ENABLE_PROCESSED_OUTPUT and ENABLE_WRAP_AT_EOL_OUTPUT modes only affect processes using ReadFile or ReadConsole and WriteFile or WriteConsole.

To change a console's I/O modes, call SetConsoleMode function.

See Also

ReadConsole, ReadConsoleInput, ReadFile, SetConsoleMode, WriteConsole, WriteFile


GetConsoleOutputCP

Windows NT: The GetConsoleOutputCP function returns the identity of the output code page used by the console associated with the calling process. A console uses its output code page to translate the character values written by the various output functions into the images displayed in the console window.

Windows 95: On Japanese and Korean implementations of Windows 95, the GetConsoleOutputCP function returns the VM code page, because the OEM code page can be either 437 or DBCS. On all other implementations of Windows 95, the GetConsoleOutputCP function returns the OEM code page.

UINT GetConsoleOutputCP(VOID)

Parameters

This function has no parameters.

Return Value

The return value is a code that identifies the code page.

Remarks

A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages.

To set a console's output code page, use the SetConsoleOutputCP function. To set and query a console's input code page, use the SetConsoleCP and GetConsoleCP functions.

See Also

GetConsoleCP, SetConsoleCP, SetConsoleOutputCP


GetConsoleScreenBufferInfo

The GetConsoleScreenBufferInfo function retrieves information about the specified console screen buffer.

BOOL GetConsoleScreenBufferInfo(

HANDLE  hConsoleOutput,	// handle of console screen buffer
PCONSOLE_SCREEN_BUFFER_INFO  lpConsoleScreenBufferInfo	// address of screen buffer info.
);
Parameters

hConsoleOutput

Identifies a console screen buffer. The handle must have GENERIC_READ access.

lpConsoleScreenBufferInfo

Points to a CONSOLE_SCREEN_BUFFER_INFO structure in which the screen buffer information is returned.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The rectangle returned in the srWindow member of the CONSOLE_SCREEN_BUFFER_INFO structure can be modified and then passed to the SetConsoleWindowInfo function to scroll the screen buffer in the window, to change the size of the window, or both.

All coordinates returned in the CONSOLE_SCREEN_BUFFER_INFO structure are in character-cell coordinates, where the origin (0, 0) is at the upper-left corner of the screen buffer.

See Also

CONSOLE_SCREEN_BUFFER_INFO, GetLargestConsoleWindowSize, SetConsoleCursorPosition, SetConsoleScreenBufferSize, SetConsoleWindowInfo


GetConsoleTitle

The GetConsoleTitle function retrieves the title bar string for the current console window.

DWORD GetConsoleTitle(

LPTSTR  lpConsoleTitle,	// address of buffer for title
DWORD  nSize	// size of the buffer
);
Parameters

lpConsoleTitle

Points to a buffer that receives a null-terminated string containing the text that appears in the title bar of the console window.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpConsoleTitle parameter.

Return Value

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

To set the title bar string for a console window, use the SetConsoleTitle function.

See Also

SetConsoleTitle


GetCPInfo

The GetCPInfo function retrieves information about any valid installed or available code page.

BOOL GetCPInfo(

UINT  CodePage,	// code page identifier
LPCPINFO  lpCPInfo	// address of structure for information
);
Parameters

CodePage

Specifies the code page about which information is to be retrieved. You can specify the code page identifier for any installed or available code page, or you can specify one of the following predefined values:

Value	Meaning
CP_ACP	Use the system default ANSI code page
CP_MACCP	Use the system default Macintosh code page
CP_OEMCP	Use the system default OEM code page
lpCPInfo

Points to a CPINFO structure that receives information about the code page.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the specified code page is not installed or not available, GetCPInfo sets the last-error value to ERROR_INVALID_PARAMETER.

See Also

GetACP, GetOEMCP, CPINFO


GetCurrencyFormat

The GetCurrencyFormat function formats a number string as a currency string for a specified locale.

int GetCurrencyFormat(

LCID  Locale,	// locale for which currency string is to be formatted
DWORD  dwFlags,	// bit flag that controls the function's operation
LPCTSTR  lpValue,	// pointer to input number string
CONST CURRENCYFMT *  lpFormat,	// pointer to a formatting information structure
LPTSTR  lpCurrencyStr,	// pointer to output buffer
int  cchCurrency	// size of output buffer
);
Parameters

Locale

Specifies the locale for which the currency string is to be formatted. If lpFormat is NULL, the function formats the string according to the currency format for this locale. If lpFormat is not NULL, the function uses the locale only for formatting information not specified in the CURRENCYFMT structure (for example, the locale's string value for the negative sign).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

A bit flag that controls the operation of the function. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify the LOCALE_NOUSEROVERRIDE flag to format the string using the system default currency format for the specified locale; or you can specify zero to format the string using any user overrides to the locale's default currency format.

lpValue

Points to a null-terminated string containing the number string to format.

This string can contain only the following characters:

•	Characters '0' through '9'

•	One decimal point (dot) if the number is a floating-point value

•	A minus sign in the first character position if the number is a negative value

All other characters are invalid. The function returns an error if the string pointed to by lpValue deviates from these rules.

lpFormat

Pointer to a CURRENCYFMT structure that contains currency formatting information. All members in the structure pointed to by lpFormat must contain appropriate values.

If lpFormat is NULL, the function uses the currency format of the specified locale.

lpCurrencyStr

Points to a buffer to receive the formatted currency string.

cchCurrency

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpCurrencyStr buffer. If cchCurrency is zero, the function returns the number of bytes or characters required to hold the formatted currency string, and the buffer pointed to by lpCurrencyStr is not used.

Return Value

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the buffer pointed to by lpCurrencyStr, or if the cchCurrency parameter is zero, the number of bytes or characters required to hold the formatted currency string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID FLAGS
ERROR_INVALID_PARAMETER

See Also

GetNumberFormat, CURRENCYFMT


GetCurrentDirectory

The GetCurrentDirectory function retrieves the current directory for the current process.

DWORD GetCurrentDirectory(

DWORD  nBufferLength,	// size, in characters, of directory buffer
LPTSTR  lpBuffer	// address of buffer for current directory
);
Parameters

nBufferLength

Specifies the length, in characters, of the buffer for the current directory string. The buffer length must include room for a terminating null character.

lpBuffer

Points to the buffer for the current directory string. This null-terminated string specifies the absolute path to the current directory.

Return Value

If the function succeeds, the return value specifies the number of characters written to the buffer, not including the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

If the buffer pointed to by lpBuffer is not large enough, the return value specifies the required size of the buffer, including the number of bytes necessary for a terminating null character.

See Also

CreateDirectory, GetSystemDirectory, GetWindowsDirectory, RemoveDirectory, SetCurrentDirectory


GetCurrentObject

The GetCurrentObject function returns the currently selected object of the specified type.

HGDIOBJ GetCurrentObject(

HDC  hdc,	// handle of device context
UINT  uObjectType	// object-type identifier
);
Parameters

hdc

Identifies the device context.

uObjectType

Specifies the object type to be queried. This parameter can be one of the following values:

Value	Meaning
OBJ_PEN	Returns the current selected pen.
OBJ_BRUSH	Returns the current selected brush.
OBJ_PAL	Returns the current selected palette.
OBJ_FONT	Returns the current selected font.
OBJ_BITMAP	Returns the current selected bitmap if hdc is a memory device context.
Return Value

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

If the function fails, the return value is NULL.

Remarks

An application can use the GetCurrentObject and GetObject functions to retrieve descriptions of the graphic objects currently selected into the given device context.

See Also

DeleteObject, GetObject, SelectObject


GetCurrentPDB

The GetCurrentPDB function is not implemented in the Win32 API. Win32-based applications should use the GetCommandLine and GetEnvironmentStrings functions.


GetCurrentPosition

The GetCurrentPosition function is not implemented in the Win32 API. Win32-based applications should use the GetCurrentPositionEx function.


GetCurrentPositionEx

The GetCurrentPositionEx function retrieves the current position in logical coordinates.

BOOL GetCurrentPositionEx(

HDC  hdc,	// handle of device context
LPPOINT  lpPoint	// address of structure receiving current position
);
Parameters

hdc

Identifies the device context.

lpPoint

Points to a POINT structure that receives the coordinates of the current position.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

MoveToEx, POINT


GetCurrentProcess

The GetCurrentProcess function returns a pseudohandle for the current process.

HANDLE GetCurrentProcess(VOID)

Parameters

This function has no parameters.

Return Value

The return value is a pseudohandle to the current process.

Remarks

A pseudohandle is a special constant that is interpreted as the current process handle. The calling process can use this handle to specify its own process whenever a process handle is required. Pseudohandles are not inherited by child processes.

This handle has the maximum possible access to the process object. For systems that support security descriptors, this is the maximum access allowed by the security descriptor for the calling process. For systems that do not support security descriptors, this is PROCESS_ALL_ACCESS.

A process can create a "real" handle to itself that is valid in the context of other processes, or that can be inherited by other processes, by specifying the pseudohandle as the source handle in a call to the DuplicateHandle function. A process can also use the OpenProcess function to open a real handle to itself.

The pseudohandle need not be closed when it is no longer needed. Calling the CloseHandle function with a pseudohandle has no effect. If the pseudohandle is duplicated by DuplicateHandle, the duplicate handle must be closed.

See Also

CloseHandle, DuplicateHandle, GetCurrentProcessId, GetCurrentThread, OpenProcess


GetCurrentProcessId

The GetCurrentProcessId function returns the process identifier of the calling process.

DWORD GetCurrentProcessId(VOID)

Parameters

This function has no parameters.

Return Value

The return value is the process identifier of the calling process.

Remarks

Until the process terminates, the process identifier uniquely identifies the process throughout the system.

See Also

GetCurrentProcess, OpenProcess


GetCurrentTask

The GetCurrentTask function is not implemented in the Win32 API. Win32-based applications should use the GetCurrentThread or GetCurrentProcess function.


GetCurrentThread

The GetCurrentThread function returns a pseudohandle for the current thread.

HANDLE GetCurrentThread(VOID)

Parameters

This function has no parameters.

Return Value

The return value is a pseudohandle for the current thread.

Remarks

A pseudohandle is a special constant that is interpreted as the current thread handle. The calling thread can use this handle to specify itself whenever a thread handle is required. Pseudohandles are not inherited by child processes.

This handle has the maximum possible access to the thread object. For systems that support security descriptors, this is the maximum access allowed by the security descriptor for the calling process. For systems that do not support security descriptors, this is THREAD_ALL_ACCESS.

The function cannot be used by one thread to create a handle that can be used by other threads to refer to the first thread. The handle is always interpreted as referring to the thread that is using it. A thread can create a "real" handle of itself that can be used by other threads, or inherited by other processes, by specifying the pseudohandle as the source handle in a call to the DuplicateHandle function.

The pseudohandle need not be closed when it is no longer needed. Calling the CloseHandle function with this handle has no effect. If the pseudohandle is duplicated by DuplicateHandle, the duplicate handle must be closed.

See Also

CloseHandle, DuplicateHandle, GetCurrentProcess, GetCurrentThreadId


GetCurrentThreadId

The GetCurrentThreadId function returns the thread identifier of the calling thread.

DWORD GetCurrentThreadId(VOID)

Parameters

This function has no parameters.

Return Value

The return value is the thread identifier of the calling thread.

Remarks

Until the thread terminates, the thread identifier uniquely identifies the thread throughout the system.

See Also

GetCurrentThread


GetCurrentTime

The GetCurrentTime function retrieves the number of milliseconds that have elapsed since Windows was started.

DWORD GetCurrentTime(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the number of milliseconds that have elapsed since Windows was started.

Remarks

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

The GetCursor function retrieves the handle of the current cursor.

HCURSOR GetCursor(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the handle of the current cursor.

If there is no cursor, the return value is NULL.

See Also

SetCursor


GetCursorPos

The GetCursorPos function retrieves the cursor's position, in screen coordinates.

BOOL GetCursorPos(

LPPOINT  lpPoint	// address of structure for cursor position
);
Parameters

lpPoint

Points to a POINT structure that receives the screen coordinates of the cursor.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The cursor position is always given in screen coordinates and is not affected by the mapping mode of the window that contains the cursor.

The calling process must have WINSTA_READATTRIBUTES access to the window station.

See Also

ClipCursor, POINT, SetCursor, SetCursorPos, ShowCursor


GetDateFormat

The GetDateFormat function formats a date as a date string for a specified locale. The function formats either a specified date or the local system date.

int GetDateFormat(

LCID  Locale,	// locale for which date is to be formatted
DWORD  dwFlags,	// flags specifying function options
CONST SYSTEMTIME *  lpDate,	// date to be formatted
LPCTSTR  lpFormat,	// date format string
LPTSTR  lpDateStr,	// buffer for storing formatted string
int  cchDate	// size of buffer
);
Parameters

Locale

Specifies the locale for which the date string is to be formatted. If lpFormat is NULL, the function formats the string according to the date format for this locale. If lpFormat is not NULL, the function uses the locale only for information not specified in the format picture string (for example, the locale's day and month names).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

A set of bit flags that specify various function options. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify a combination of the following flags:

Flag	Meaning
LOCALE_NOUSEROVERRIDE	If set, the function formats the string using the system default date format for the specified locale. If not set, the function formats the string using any user overrides to the locale's default date format.
DATE_SHORTDATE	Use the short date format. This is the default. Cannot be used with DATE_LONGDATE.
DATE_LONGDATE	Use the long date format. Cannot be used with DATE_SHORTDATE.
DATE_USE_ALT_CALENDAR	Use the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that alternate calendar, rather than using any user overrides. The user overrides will be used only in the event that there is no default format for the specified alternate calendar.
lpDate

Pointer to a SYSTEMTIME structure that contains the date information to be formatted. If this pointer is NULL, the function uses the current local system date.

lpFormat

Pointer to a format picture string to use to form the date string. If lpFormat is NULL, the function uses the date format of the specified locale.

Use the following elements to construct a format picture string. If you use spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown in the table (for example, "MM" not "mm"). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.

Picture	Meaning
d	Day of month as digits with no leading zero for single-digit days.
dd	Day of month as digits with leading zero for single-digit days.
ddd	Day of week as a three-letter abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
dddd	Day of week as its full name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
M	Month as digits with no leading zero for single-digit months.
MM	Month as digits with leading zero for single-digit months.
MMM	Month as a three-letter abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMM	Month as its full name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
y	Year as last two digits, but with no leading zero for years less than 10.
yy	Year as last two digits, but with leading zero for years less than 10.
yyyy	Year represented by full four digits.
gg	Period/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string.
For example, to get the date string

"Wed, Aug 31 94"

use the following picture string:

"ddd',' MMM dd yy"

lpDateStr

Pointer to a buffer that receives the formatted date string.

cchDate

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpDateStr buffer. If cchDate is zero, the function returns the number of bytes or characters required to hold the formatted date string, and the buffer pointed to by lpDateStr is not used.

Return Value

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the lpDateStr buffer, or if the cchDate parameter is zero, the number of bytes or characters required to hold the formatted date string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

The day name, abbreviated day name, month name, and abbreviated month name are all localized based on the given locale identifier.

The date values in the SYSTEMTIME structure pointed to by lpDate must be valid. The function checks each of the date values: year, month, day, and day of week. If the day of the week is incorrect, the function uses the correct value, and returns no error. If any of the other date values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER.

The function ignores the time portions of the SYSTEMTIME structure pointed to by lpDate: wHour, wMinute, wSecond, and wMilliseconds.

The DATE_SHORTDATE and DATE_LONGDATE flag options are mutually exclusive. If neither one is specified and lpFormat is NULL, then DATE_SHORTDATE is the default.

No errors are returned for a bad format string. The function simply forms the best date string that it can. For example, the only year pictures that are valid are L"yyyy" and L"yy" (the 'L' indicates a Unicode (16-bit characters) string). If L"y" is passed in, the function  assumes L"yy". If L"yyy" is passed in, the function assumes L"yyyy". If more than 4 date (L"dddd") or 4 month (L"MMMM") pictures are passed in, then the function defaults to L"dddd" or L"MMMM".

Any text that should remain in its exact form in the date string should be enclosed within single quotation marks in the date format picture. The single quotation mark may also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as "May '93", the format string would be:  L"MMMM ''''yy" The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.

See Also

GetTimeFormat, SYSTEMTIME


GetDC

The GetDC function retrieves a handle of a display device context (DC) for the client area of the specified window. The display device context can be used in subsequent GDI functions to draw in the client area of the window.

This function retrieves a common, class, or private device context depending on the class style specified for the specified window. For common device contexts, GetDC assigns default attributes to the device context each time it is retrieved. For class and private device contexts, GetDC leaves the previously assigned attributes unchanged.

HDC GetDC(

HWND  hWnd	// handle of window
);
Parameters

hWnd

Identifies the window whose device context is to be retrieved.

Return Value

If the function succeeds, the return value identifies the device context for the given window's client area.

If the function fails, the return value is NULL.

Remarks

After painting with a common device context, the ReleaseDC function must be called to release the device context. Class and private device contexts do not have to be released. The number of device contexts is limited only by available memory.

See Also

ReleaseDC, GetWindowDC


GetDCEx

The GetDCEx function retrieves the handle of a display device (DC) context for the specified window. The display device context can be used in subsequent GDI functions to draw in the client area.

This function is an extension to the GetDC function that gives an application more control over how and whether clipping occurs in the client area.

HDC GetDCEx(

HWND  hWnd,	// handle of window
HRGN  hrgnClip,	// handle of clip region
DWORD  flags	// device-context creation flags
);
Parameters

hWnd

Identifies the window where drawing will occur.

hrgnClip

Specifies a clipping region that may be combined with the visible region of the client window.

flags

Specifies how the device context is created. This parameter can be a combination of the following values:

Value	Meaning
DCX_WINDOW	Returns a device context corresponding to the window rectangle rather than the client rectangle.
DCX_CACHE	Returns a device context from the cache, rather than the OWNDC or CLASSDC window. Essentially overrides CS_OWNDC and CS_CLASSDC.
DCX_PARENTCLIP	Uses the visible region of the parent window. The parent's WS_CLIPCHILDREN and CS_PARENTDC style bits are ignored. The device context origin is set to the upper-left corner of the window identified by hWnd.
DCX_CLIPSIBLINGS	Excludes the visible regions of all sibling windows above the window identified by hWnd.
DCX_CLIPCHILDREN	Excludes the visible regions of all child windows below the window identified by hWnd.
DCX_NORESETATTRS	Does not reset the attributes of this device context to the default attributes when this device context is released.
DCX_LOCKWINDOWUPDATE	Allows drawing even if there is a LockWindowUpdate call in effect that would otherwise exclude this window. Used for drawing during tracking.
DCX_EXCLUDERGN	The clipping region identified by hrgnClip is excluded from the visible region of the returned device context.
DCX_INTERSECTRGN	The clipping region identified by hrgnClip is intersected with the visible region of the returned device context.
DCX_VALIDATE	When specified with DCX_INTERSECTUPDATE, causes the device context to be completely validated. Using this function with both DCX_INTERSECTUPDATE and DCX_VALIDATE is identical to using the BeginPaint function.
Return Value

If the function succeeds, the return value is the handle of the device context for the given window.

If the function fails, the return value is NULL. An invalid value for the hWnd parameter will cause the function to fail.

Remarks

Unless the display device context belongs to a window class, the ReleaseDC function must be called to release the device context after painting. Because only five common device contexts are available at any given time, failure to release a device context can prevent other applications from accessing a device context.

A device context belonging to the window's class is returned by the GetDC function if CS_CLASSDC, CS_OWNDC or CS_PARENTDC was specified as a style in the WNDCLASS structure when the class was registered.

See Also

BeginPaint, GetDC, GetWindowDC, ReleaseDC WNDCLASS


GetDCOrg

The GetDCOrg function is not implemented in the Win32 API. Win32-based applications should use the GetDCOrgEx function.


GetDCOrgEx

The GetDCOrgEx function obtains the final translation origin for a specified device context (DC). The final translation origin specifies an offset that Windows uses to translate device coordinates into client coordinates (for coordinates in an application's window). This function supersedes the GetDCOrg function.

BOOL GetDCOrgEx(

HDC  hdc,	// device-context handle
LPPOINT  lpPoint	// address of structure that receives translation origin
);
Parameters

hdc

Specifies the device context whose final translation origin is to be retrieved.

lpPoint

Points to a POINT structure that the function will set to the final translation origin, in device coordinates.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The final translation origin is relative to the physical origin of the screen.

See Also

CreateIC, POINT


GetDefaultCommConfig  (preliminaryWindows 95)
GetDefaultCommConfig  (preliminary−Windows 95)

The GetDefaultCommConfig function gets the default configuration for a communications device.

BOOL GetDefaultCommConfig(

LPCSTR  lpszName,
LPCOMMCONFIG  lpCC,
LPDWORD  lpdwSize
);
Parameters

lpszName

Points to a null-terminated string specifying the name of the device.

lpCC

Points to the buffer that receives the COMMCONFIG structure.

lpdwSize

Points to a 32-bit variable that specifies the size, in bytes, of the buffer pointed to by lpCC. Upon return, the variable contains the number of bytes copied if the function succeeds, or the number of bytes required if the buffer was too small.

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

See Also

COMMCONFIG


GetDesktopWindow

The GetDesktopWindow function returns the handle of the Windows desktop window. The desktop window covers the entire screen. The desktop window is the area on top of which all icons and other windows are painted.

HWND GetDesktopWindow(VOID)

Parameters

This function has no parameters.

Return Value

The return value is the handle of the desktop window.

See Also

GetWindow


GetDeviceCaps

The GetDeviceCaps function retrieves device-specific information about a specified device.

int GetDeviceCaps(

HDC  hdc,	// device-context handle
int  nIndex	// index of capability to query
);
Parameters

hdc

Identifies the device context.

nIndex

Specifies the item to return. This parameter can be one of the following values:

Index	Meaning
DRIVERVERSION	The device driver version.
TECHNOLOGY	Device technology. It can be any one of the following values:
Value	Meaning
DT_PLOTTER	Vector plotter
DT_RASDISPLAY	Raster display
DT_RASPRINTER	Raster printer
DT_RASCAMERA	Raster camera
DT_CHARSTREAM	Character stream
DT_METAFILE	Metafile
DT_DISPFILE	Display file
	If the hdc parameter identifies the device context of an enhanced metafile, the device technology is that of the referenced device as given to the CreateEnhMetaFile function. To determine whether it is an enhanced metafile device context, use the GetObjectType function.
HORZSIZE	Width, in millimeters, of the physical screen.
VERTSIZE	Height, in millimeters, of the physical screen.
HORZRES	Width, in pixels, of the screen.
VERTRES	Height, in raster lines, of the screen.
LOGPIXELSX	Number of pixels per logical inch along the screen width.
LOGPIXELSY	Number of pixels per logical inch along the screen height.
BITSPIXEL	Number of adjacent color bits for each pixel.
PLANES	Number of color planes.
NUMBRUSHES	Number of device-specific brushes.
NUMPENS	Number of device-specific pens.
NUMFONTS	Number of device-specific fonts.
NUMCOLORS	Number of entries in the device's color table.
ASPECTX	Relative width of a device pixel used for line drawing.
ASPECTY	Relative height of a device pixel used for line drawing.
ASPECTXY	Diagonal width of the device pixel used for line drawing.
PDEVICESIZE	Reserved.
CLIPCAPS	Flag that indicates the clipping capabilities of the device. If the device can clip to a rectangle, it is 1. Otherwise, it is 0.
SIZEPALETTE	Number of entries in the system palette. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with Windows version 3.0 or later.
NUMRESERVED	Number of reserved entries in the system palette. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with Windows version 3.0 or later.
COLORRES	Actual color resolution of the device, in bits per pixel. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with Windows version 3.0 or later.
PHYSICALWIDTH	For printing devices: the physical width, in device units.
PHYSICALHEIGHT	For printing devices: the physical height, in device units.
PHYSICALOFFSETX	For printing devices: the physical printable area horizontal margin.
PHYSICALOFFSETY	For printing devices: the physical printable area vertical margin.
SCALINGFACTORX	For printing devices: the scaling factor along the horizontal axis.
SCALINGFACTORY	For printing devices: the scaling factor along the vertical axis.
VREFRESH	Windows NT only: For display devices: the current vertical refresh rate of the device, in cycles per second (Hz).
DESKTOPHORZRES	Windows NT only: Width, in pixels, of the virtual desktop. This value may be larger than HORZRES if the device supports a virtual desktop or multiple displays.
DESKTOPVERTRES	Windows NT only: Height, in pixels, of the virtual desktop. This value may be larger than VERTRES if the device supports a virtual desktop or multiple displays.
BLTALIGNMENT	Windows NT only: Preferred horizontal drawing alignment, expressed as a multiple of pixels. For best drawing performance, windows should be horizontally aligned to a multiple of this value. A value of zero indicates that the device is accelerated, and any alignment may be used.
RASTERCAPS	Value that indicates the raster capabilities of the device, as shown in the following table:
Capability	Meaning
RC_BANDING	Requires banding support.
RC_BITBLT	Capable of transferring bitmaps.
RC_BITMAP64	Capable of supporting bitmaps larger than 64K.
RC_DI_BITMAP	Capable of supporting the SetDIBits and GetDIBits functions.
RC_DIBTODEV	Capable of supporting the SetDIBitsToDevice function.
RC_FLOODFILL	Capable of performing flood fills.
RC_GDI20_OUTPUT	Capable of supporting features of Windows 2.0.
RC_PALETTE	Specifies a palette-based device.
RC_SCALING	Capable of scaling.
RC_STRETCHBLT	Capable of performing the StretchBlt function.
RC_STRETCHDIB	Capable of performing the StretchDIBits function.
CURVECAPS	Value that indicates the curve capabilities of the device, as shown in the following table:
Value	Meaning
CC_NONE	Device does not support curves.
CC_CIRCLES	Device can draw circles.
CC_PIE	Device can draw pie wedges.
CC_CHORD	Device can draw chord arcs.
CC_ELLIPSES	Device can draw ellipses.
CC_WIDE	Device can draw wide borders.
CC_STYLED	Device can draw styled borders.
CC_WIDESTYLED	Device can draw borders that are wide and styled.
CC_INTERIORS	Device can draw interiors.
CC_ROUNDRECT	Device can draw rounded rectangles.
LINECAPS	Value that indicates the line capabilities of the device, as shown in the following table:
Value	Meaning
LC_NONE	Device does not support lines.
LC_POLYLINE	Device can draw a polyline.
LC_MARKER	Device can draw a marker.
LC_POLYMARKER	Device can draw multiple markers.
LC_WIDE	Device can draw wide lines.
LC_STYLED	Device can draw styled lines.
LC_WIDESTYLED	Device can draw lines that are wide and styled.
LC_INTERIORS	Device can draw interiors.
POLYGONALCAPS	Value that indicates the polygon capabilities of the device, as shown in the following table:
Value	Meaning
PC_NONE	Device does not support polygons.
PC_POLYGON	Device can draw alternate-fill polygons.
PC_RECTANGLE	Device can draw rectangles.
PC_WINDPOLYGON	Device can draw winding-fill polygons.
PC_SCANLINE	Device can draw a single scanline.
PC_WIDE	Device can draw wide borders.
PC_STYLED	Device can draw styled borders.
PC_WIDESTYLED	Device can draw borders that are wide and styled.
PC_INTERIORS	Device can draw interiors.
TEXTCAPS	Value that indicates the text capabilities of the device, as shown in the following table:
Bit	Meaning
TC_OP_CHARACTER	Device is capable of character output precision.
TC_OP_STROKE	Device is capable of stroke output precision.
TC_CP_STROKE	Device is capable of stroke clip precision.
TC_CR_90	Device is capable of 90-degree character rotation.
TC_CR_ANY	Device is capable of any character rotation.
TC_SF_X_YINDEP	Device can scale independently in the x- and y-directions.
TC_SA_DOUBLE	Device is capable of doubled character for scaling.
TC_SA_INTEGER	Device uses integer multiples only for character scaling.
TC_SA_CONTIN	Device uses any multiples for exact character scaling.
TC_EA_DOUBLE	Device can draw double-weight characters.
TC_IA_ABLE	Device can italicize.
TC_UA_ABLE	Device can underline.
TC_SO_ABLE	Device can draw strikeouts.
TC_RA_ABLE	Device can draw raster fonts.
TC_VA_ABLE	Device can draw vector fonts.
TC_RESERVED	Reserved; must be zero.
TC_SCROLLBLT	Device cannot scroll using a bit-block transfer. Note that this meaning may be the opposite of what you expect.
Return Value

The return value specifies the value of the desired item.

See Also

CreateEnhMetaFile, CreateIC, DeviceCapabilities, GetDIBits, GetObjectType, SetDIBits, SetDIBitsToDevice, StretchBlt, StretchDIBits


GetDeviceGammaRamp  (preliminaryWindows 95)
GetDeviceGammaRamp  (preliminary−Windows 95)

The GetDeviceGammaRamp function retrieves the gamma ramp on direct color display boards.

BOOL GetDeviceGammaRamp(

HDC  hdc,
LPVOID  lpRamp
);
Parameters

hdc

Handle to the device context.

lpRamp

Pointer to a set of three arrays of 256-byte elements. These arrays are the mapping between color values in the frame buffer and DAC values. The first array is red, the next is green, and the final one is blue.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Direct color display modes do not use color lookup tables. The direct color modes are usually 16-, 24-, or 32-bit. Not all direct color video boards support loadable gamma ramps. This function succeeds only for those drivers that support loadable gamma ramps in hardware.


GetDialogBaseUnits

The GetDialogBaseUnits function returns the dialog box base units used by Windows to create dialog boxes. Both Windows and applications use these units to convert the width and height of dialog boxes and controls from dialog units, as given in dialog box templates, to pixels, and vice versa.

LONG GetDialogBaseUnits(VOID)

Parameters

This function has no parameters.

Return Value

The return value is a 32-bit value that contains the dialog base units. The low-order word of the return value contains the horizontal dialog box base unit, and the high-order word contains the vertical dialog box base unit.

Remarks

The horizontal base unit is equal to the average width, in pixels, of the characters in the system font; the vertical base unit is equal to the height, in pixels, of the font. Furthermore, each horizontal base unit is equal to 4 horizontal dialog units; each vertical base unit is equal to 8 vertical dialog units. Therefore, to convert dialog units to pixels, an application applies the following formulas:

pixelX = (dialogunitX * baseunitX) / 4

pixelY = (dialogunitY * baseunitY) / 8

Similarly, to convert from pixels to dialog units, an application applies the following formulas:

dialogunitX = (pixelX * 4) / baseunitX

dialogunitY = (pixelY * 8) / baseunitY

The multiplication is performed before the division to avoid rounding problems if base units are not divisible by 4 or 8.

See Also

MapDialogRect


GetDIBColorTable

The GetDIBColorTable function retrieves RGB (red, green, blue) color values from a range of entries in the color table of the DIB section bitmap that is currently selected into a specified device context.

UINT GetDIBColorTable(

HDC hdc,	// handle of device context whose DIB is of interest
UINT uStartIndex,	// color table index of first entry to retrieve
UINT cEntries,	// number of color table entries to retrieve
RGBQUAD *pColors	// pointer to buffer that receives color table entries
);
Parameters

hdc

Specifies a device context. A DIB section bitmap must be selected into this device context.

uStartIndex

A zero-based color table index that specifies the first color table entry to retrieve.

cEntries

Specifies the number of color table entries to retrieve.

pColors

Points to a buffer that receives an array of RGBQUAD data structures containing color information from the DIB's color table. The buffer must be large enough to contain as many RGBQUAD data structures as the value of cEntries.

Return Value

If the function succeeds, the return value is the number of color table entries that the function retrieves.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetDIBColorTable function should be called to retrieve the color table for DIB section bitmaps that use 1, 4, or 8 bits per pixel. The biBitCount member of a bitmap's associated BITMAPINFOHEADER structure specifies the number of bits per pixel. DIB section bitmaps with a biBitCount value greater than 8 do not have a color table, but they do have associated color masks. Call the GetObject function to retrieve those color masks.

See Also

BITMAPINFOHEADER, CreateDIBSection, DIBSECTION, GetObject, RGBQUAD, SetDIBColorTable


GetDIBits

The GetDIBits function retrieves the bits of the specified bitmap and copies them into a buffer using the specified format.

int GetDIBits(

HDC  hdc,	// handle of device context
HBITMAP  hbmp,	// handle of bitmap
UINT  uStartScan,	// first scan line to set in destination bitmap
UINT  cScanLines,	// number of scan lines to copy
LPVOID  lpvBits,	// address of array for bitmap bits
LPBITMAPINFO  lpbi,	// address of structure with bitmap data
UINT  uUsage	// RGB or palette index
);
Parameters

hdc

Identifies the device context.

hbmp

Identifies the bitmap.

uStartScan

Specifies the first scan line to retrieve.

cScanLines

Specifies the number of scan lines to retrieve.

lpvBits

Points to a buffer to receive the bitmap data. If this parameter is NULL, the function passes the dimensions and format of the bitmap to the BITMAPINFO structure pointed to by the lpbi parameter.

lpbi

Points to a BITMAPINFO structure that specifies the desired format for the device-independent bitmap (DIB) data.

uUsage

Specifies the format of the bmiColors member of the BITMAPINFO structure. It must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	The color table should consist of an array of 16-bit indices into the current logical palette.
DIB_RGB_COLORS	The color table should consist of literal red, green, blue (RGB) values.
Return Value

If the function succeeds, the return value is the number of scan lines copied from the bitmap.

If the function fails, the return value is zero.

Remarks

If the requested format for the DIB matches its internal format, the RGB values for the bitmap are copied. If the requested format doesn't match the internal format, a color table is synthesized. The following table describes the color table synthesized for each format.

Value	Meaning
1_BPP	The color table consists of a black and a white entry.
4_BPP	The color table consists of a mix of colors identical to the standard VGA palette.
8_BPP	The color table consists of a general mix of 256 colors defined by GDI. (Included in these 256 colors are the 20 colors found in the default logical palette.)
24_BPP	No color table is returned.
If the lpvBits parameter is a valid pointer, the first six members of the BITMAPINFOHEADER structure must be initialized to specify the size and format of the DIB. Note that a bottom-up DIB is specified by setting the height to a positive number, while a top-down DIB is specified by setting the height to a negative number. The bitmap's color table will be appended to the BITMAPINFO structure.

If lpvBits is NULL, GetDIBits examines the first member of the first structure pointed to by lpbi. This member must specify the size, in bytes, of a BITMAPCOREHEADER or a BITMAPINFOHEADER structure. The function uses the specified size to determine how the remaining members should be initialized.

If lpvBits is NULL and the bit count member of BITMAPINFO is initialized to zero, GetDIBits fills in BITMAPINFOHEADER or BITMAPCOREHEADER without the color table. This technique can be used to query bitmap attributes.

The bitmap identified by the hbmp parameter must not be selected into a device context when the application calls this function.

The origin for a bottom-up DIB is the lower-left corner of the bitmap; the origin for a top-down DIB is the upper-left corner.

See Also

BITMAPCOREHEADER, BITMAPINFO, BITMAPINFOHEADER, SetDIBits


GetDiskFreeSpace

The GetDiskFreeSpace function retrieves information about the specified disk, including the amount of free space on the disk.

BOOL GetDiskFreeSpace(

LPCTSTR  lpRootPathName,	// address of root path
LPDWORD  lpSectorsPerCluster,	// address of sectors per cluster
LPDWORD  lpBytesPerSector,	// address of bytes per sector
LPDWORD  lpNumberOfFreeClusters,	// address of number of free clusters
LPDWORD  lpTotalNumberOfClusters	// address of total number of clusters
);
Parameters

lpRootPathName

Points to a null-terminated string that specifies the root directory of the disk to return information about. If lpRootPathName is NULL, the function uses the root of the current directory.

lpSectorsPerCluster

Points to a variable for the number of sectors per cluster.

lpBytesPerSector

Points to a variable for the number of bytes per sector.

lpNumberOfFreeClusters

Points to a variable for the total number of free clusters on the disk.

lpTotalNumberOfClusters

Points to a variable for the total number of clusters on the disk.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetDriveType


GetDlgCtrlID

The GetDlgCtrlID function returns the identifier of the specified control.

int GetDlgCtrlID(

HWND  hwndCtl	// handle of control
);
Parameters

hwndCtl

Identifies the control.

Return Value

If the function succeeds, the return value is the identifier of the control.

If the function fails, the return value is NULL. An invalid value for the hwndCtl parameter, for example, will cause the function to fail.

Remarks

GetDlgCtrlID accepts child window handles as well as handles of controls in dialog boxes. An application sets the identifier for a child window when it creates the window by assigning the identifier value to the hmenu parameter when calling the CreateWindow or CreateWindowEx function.

Although GetDlgCtrlID may return a value if hwndCtl identifies a top-level window, top-level windows cannot have identifiers and such a return value is never valid.

See Also

CreateWindow, CreateWindowEx, GetDlgItem


GetDlgItem

The GetDlgItem function retrieves the handle of a control in the specified dialog box.

HWND GetDlgItem(

HWND  hDlg,	// handle of dialog box
int  nIDDlgItem	// identifier of control
);
Parameters

hDlg

Identifies the dialog box that contains the control.

nIDDlgItem

Specifies the identifier of the control to be retrieved.

Return Value

If the function succeeds, the return value is the window handle of the given control.

If the function fails, the return value is NULL, indicating an invalid dialog box handle or a nonexistent control.

Remarks

You can use the GetDlgItem function with any parent-child window pair, not just with dialog boxes. As long as the hDlg parameter specifies a parent window and the child window has a unique identifier (as specified by the hMenu parameter in the CreateWindow or CreateWindowEx function that created the child window), GetDlgItem returns a valid handle to the child window.

See Also

CreateWindow, CreateWindowEx, GetDlgItemInt, GetDlgItemText


GetDlgItemInt

The GetDlgItemInt function translates the text of a specified control in a dialog box into an integer value.

UINT GetDlgItemInt(

HWND  hDlg,	// handle to dialog box
int  nIDDlgItem,	// control identifier
BOOL*  lpTranslated,	// points to variable to receive success/failure indicator
BOOL  bSigned	// specifies whether value is signed or unsigned
);
Parameters

hDlg

Handle to the dialog box that contains the control of interest.

nIDDlgItem

Dialog item identifier that specifies the control whose text is to be translated.

lpTranslated

Points to a Boolean variable that receives a function success/failure value. TRUE indicates success, FALSE indicates failure.

This parameter is optional: it can be NULL. In that case, the function returns no information about success or failure.

bSigned

Specifies whether the function should examine the text for a minus sign at the beginning and return a signed integer value if it finds one. TRUE specifies that this should be done, FALSE that it should not.

Return Value

If the function succeeds, the variable pointed to by lpTranslated is set to TRUE, and the return value is the translated value of the control text.

If the function fails, the variable pointed to by lpTranslated is set to FALSE, and the return value is zero. Note that, since zero is a possible translated value, a return value of zero does not by itself indicate failure.

If lpTranslated is NULL, the function returns no information about success or failure.

If the bSigned parameter is TRUE, specifying that the value to be retrieved is a signed integer value, cast the return value to an int type.

Remarks

The GetDlgItemInt function retrieves the text of the given control by sending the control a WM_GETTEXT message. The function translates the retrieved text by stripping any extra spaces at the beginning of the text and then converting the decimal digits. The function stops translating when it reaches the end of the text or encounters a nonnumeric character.

If the bSigned parameter is TRUE, the GetDlgItemInt function checks for a minus sign (−) at the beginning of the text and translates the text into a signed integer value. Otherwise, the function creates an unsigned integer value.

The GetDlgItemInt function returns zero if the translated value is greater than INT_MAX (for signed numbers) or UINT_MAX (for unsigned numbers).

See Also

GetDlgCtrlID, GetDlgItem, GetDlgItemText, SetDlgItemInt


GetDlgItemText

The GetDlgItemText function retrieves the title or text associated with a control in a dialog box.

UINT GetDlgItemText(

HWND  hDlg,	// handle of dialog box
int  nIDDlgItem,	// identifier of control
LPTSTR  lpString,	// address of buffer for text
int  nMaxCount	// maximum size of string
);
Parameters

hDlg

Identifies the dialog box that contains the control.

nIDDlgItem

Specifies the identifier of the control whose title or text is to be retrieved.

lpString

Points to the buffer to receive the title or text.

nMaxCount

Specifies the maximum length, in characters, of the string to be copied to the buffer pointed to by lpString. If the length of the string exceeds the limit, the string is truncated.

Return Value

If the function succeeds, the return value specifies the number of characters copied to the buffer, not including the terminating null character.

If the function fails, the return value is zero.

Remarks

The GetDlgItemText function sends a WM_GETTEXT message to the control.

See Also

GetDlgItemInt, SetDlgItemInt, SetDlgItemText, WM_GETTEXT


GetDOSEnvironment

The GetDOSEnvironment function is not implemented in the Win32 API. Win32-based applications should use the GetEnvironmentStrings function.


GetDoubleClickTime

The GetDoubleClickTime function retrieves the current double-click time for the mouse. A double-click is a series of two clicks of the mouse button, the second occurring within a specified time after the first. The double-click time is the maximum number of milliseconds that may occur between the first and second click of a double-click.

UINT GetDoubleClickTime(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value specifies the current double-click time, in milliseconds.

See Also

SetDoubleClickTime


GetDriveType

The GetDriveType function determines whether a disk drive is a removable, fixed, CD-ROM, RAM disk, or network drive.

UINT GetDriveType(

LPCTSTR  lpRootPathName	// address of root path
);
Parameters

lpRootPathName

Points to a null-terminated string that specifies the root directory of the disk to return information about. If lpRootPathName is NULL, the function uses the root of the current directory.

Return Value

The return value specifies the type of drive. It can be one of the following values:

Value	Meaning
0	The drive type cannot be determined.
1	The root directory does not exist.
DRIVE_REMOVABLE	The drive can be removed from the drive.
DRIVE_FIXED	The disk cannot be removed from the drive.
DRIVE_REMOTE	The drive is a remote (network) drive.
DRIVE_CDROM	The drive is a CD-ROM drive.
DRIVE_RAMDISK	The drive is a RAM disk.
See Also

GetDiskFreeSpace


GetEffectiveClientRect  (preliminaryWindows NT)
GetEffectiveClientRect  (preliminary−Windows NT)

The GetEffectiveClientRect function calculates the dimensions of a rectangle in the client area. This function has limited utility.

void GetEffectiveClientRect(

HWND  hWnd,
LPRECT  lprc,
LPINT  lpInfo
);
Parameters

hWnd

Handle to the window that has the client area to check.

lprc

Pointer to a RECT structure that receives the dimensions of the rectangle.

lpInfo

Pointer to an array of 16-bit control identifiers for controls in the client area. Each control requires two array elements. The first element must be nonzero, and the second element must be the control identifier. The last element in the array must be zero.

Return Value

This function does not return a value.

See Also

RECT


GetEnhMetaFile

The GetEnhMetaFile function creates a handle that identifies the enhanced-format metafile stored in the specified file.

HENHMETAFILE GetEnhMetaFile(

LPCTSTR  lpszMetaFile	// address of metafile name
);
Parameters

lpszMetaFile

Points to the null-terminated string that specifies the name of an enhanced metafile.

Return Value

If the function succeeds, the return value is a handle of the enhanced metafile.

If the function fails, the return value is NULL.

Remarks

When the application no longer needs an enhanced-metafile handle, it should delete the handle by calling the DeleteEnhMetaFile function.

A Windows-format metafile must be converted to the enhanced format before it can be processed by the GetEnhMetaFile function. To convert the file, use the SetWinMetaFileBits function.

Where text arguments must use Unicode characters, use this function as a wide-character function. Where text arguments must use characters from the Windows 3.x character set, use this function as an ANSI function.

See Also

DeleteEnhMetaFile, GetEnhMetaFile, SetWinMetaFileBits


GetEnhMetaFileBits

The GetEnhMetaFileBits function retrieves the contents of the specified enhanced-format metafile and copies them into a buffer.

UINT GetEnhMetaFileBits(

HENHMETAFILE  hemf,	// handle of metafile
UINT  cbBuffer,	// size of data buffer, in bytes
LPBYTE  lpbBuffer	// address of data buffer
);
Parameters

hemf

Identifies the enhanced metafile.

cbBuffer

Specifies the size, in bytes, of the buffer to receive the data.

lpbBuffer

Points to the buffer to receive the metafile data. The buffer must be sufficiently large to contain the data. If lpbBuffer is NULL, the function returns the size necessary to hold the data.

Return Value

If the function succeeds and the buffer pointer is NULL, the return value is the size of the enhanced metafile, in bytes.

If the function succeeds and the buffer pointer is a valid pointer, the return value is the number of bytes copied to the buffer.

If the function fails, the return value is zero.

Remarks

After the enhanced-metafile bits are retrieved, they can be used to create a memory-based metafile by calling the SetEnhMetaFileBits function.

The GetEnhMetaFileBits function does not invalidate the enhanced-metafile handle. The application must call the DeleteEnhMetaFile function to delete the handle when it is no longer needed.

The metafile contents retrieved by this function are in the enhanced format. To retrieve the metafile contents in the Windows format, use the GetWinMetaFileBits function.

See Also

DeleteEnhMetaFile, GetWinMetaFileBits, SetEnhMetaFileBits


GetEnhMetaFileDescription

The GetEnhMetaFileDescription function retrieves an optional text description from an enhanced-format metafile and copies the string to the specified buffer.

UINT GetEnhMetaFileDescription(

HENHMETAFILE  hemf,	// handle of enhanced metafile
UINT  cchBuffer,	// size of text buffer, in characters
LPTSTR  lpszDescription	// address of text buffer
);
Parameters

hemf

Identifies the enhanced metafile.

cchBuffer

Specifies the size, in characters, of the buffer to receive the data. Only this many characters will be copied.

lpszDescription

Points to the buffer to receive the optional text description.

Return Value

If the optional text description exists and the buffer pointer is NULL, the return value is the length of the text string, in characters.

If the optional text description exists and the buffer pointer is a valid pointer, the return value is the number of characters copied into the buffer.

If the optional text description does not exist, the return value is zero.

If the function fails, the return value is GDI_ERROR.

Remarks

The optional text description contains two strings, the first identifying the application that created the enhanced metafile and the second identifying the picture contained in the metafile. The strings are separated by a null character and terminated with two null characters — for example, "XYZ Graphics Editor\0Bald Eagle\0\0" where \0 represents the null character.

Where text arguments must use Unicode characters, use this function as a wide-character function. Where text arguments must use characters from the Windows 3.x character set, use this function as an ANSI function.

See Also

CreateEnhMetaFile


GetEnhMetaFileHeader

The GetEnhMetaFileHeader function retrieves the record containing the header for the specified enhanced-format metafile.

UINT GetEnhMetaFileHeader(

HENHMETAFILE  hemf,	// handle of enhanced metafile
UINT  cbBuffer,	// size of buffer, in bytes
LPENHMETAHEADER  lpemh	// address of buffer to receive data
);
Parameters

hemf

Identifies the enhanced metafile for which the header is to be retrieved.

cbBuffer

Specifies the size, in bytes, of the buffer to receive the data. Only this many bytes will be copied.

lpemh

Points to an ENHMETAHEADER structure to receive the header record. If this parameter is NULL, the function returns the size of the header record.

Return Value

If the function succeeds and the structure pointer is NULL, the return value is the size of the record that contains the header; if the structure pointer is a valid pointer, the return value is the number of bytes copied. Otherwise, it is zero.

Remarks

An enhanced-metafile header contains such information as the metafile's size, in bytes; the dimensions of the picture stored in the metafile; the number of records stored in the metafile; the offset to the optional text description; the size of the optional palette, and the resolution of the device on which the picture was created.

The record that contains the enhanced-metafile header is always the first record in the metafile.

See Also

ENHMETAHEADER, PlayEnhMetaFile


GetEnhMetaFilePaletteEntries

The GetEnhMetaFilePaletteEntries function retrieves optional palette entries from the specified enhanced metafile.

UINT GetEnhMetaFilePaletteEntries(

HENHMETAFILE  hemf,	// handle of enhanced metafile
UINT  cEntries,	// count of palette entries
LPPALETTEENTRY  lppe	// address of palette-entry array
);
Parameters

hemf

Identifies the enhanced metafile.

cEntries

Specifies the number of entries to be retrieved from the optional palette.

lppe

Points to an array of PALETTEENTRY structures to receive the palette colors. The array must contain at least as many structures as there are entries specified by the cEntries parameter.

Return Value

If the array pointer is NULL and the enhanced metafile contains an optional palette, the return value is the number of entries in the enhanced metafile's palette; if the array pointer is a valid pointer and the enhanced metafile contains an optional palette, the return value is the number of entries copied; if the metafile does not contain an optional palette, the return value is zero. Otherwise, the return value is GDI_ERROR.

Remarks

An application can store an optional palette in an enhanced metafile by calling the CreatePalette and SetPaletteEntries functions before creating the picture and storing it in the metafile. By doing this, the application can achieve consistent colors when the picture is displayed on a variety of devices.

An application that displays a picture stored in an enhanced metafile can call the GetEnhMetaFilePaletteEntries function to determine whether the optional palette exists. If it does, the application can call the GetEnhMetaFilePaletteEntries function a second time to retrieve the palette entries and then create a logical palette (by using the CreatePalette function), select it into its device context (by using the SelectPalette function), and then realize it (by using the RealizePalette function). After the logical palette has been realized, calling the PlayEnhMetaFile function displays the picture using its original colors.

See Also

CreatePalette, PALETTEENTRY, PlayEnhMetaFile, RealizePalette, SelectPalette


GetEnvironmentStrings

The GetEnvironmentStrings function returns the address of the environment block for the current process. This function replaces the GetDOSEnvironment function.

LPVOID GetEnvironmentStrings(VOID)

Parameters

This function has no parameters.

Return Value

The return value is a pointer to an environment block for the current process.

Remarks

Do not use the return value of GetEnvironmentStrings to get or set environment variables. Instead, use the GetEnvironmentVariable and SetEnvironmentVariable functions to access the environment variables within this block. When the block is no longer needed, it should be freed by calling FreeEnvironmentStrings.

A process can use this function's return value to specify the environment address used by the CreateProcess function.

See Also

CreateProcess, GetEnvironmentVariable, SetEnvironmentVariable, FreeEnvironmentStrings


GetEnvironmentVariable

The GetEnvironmentVariable function retrieves the value of the specified variable from the environment block of the calling process. The value is in the form of a null-terminated string of characters.

DWORD GetEnvironmentVariable(

LPCTSTR  lpName,	// address of environment variable name
LPTSTR  lpBuffer,	// address of buffer for variable value
DWORD  nSize	// size of buffer, in characters
);
Parameters

lpName

Points to a null-terminated string that specifies the environment variable.

lpBuffer

Points to a buffer to receive the value of the specified environment variable.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpBuffer parameter.

Return Value

If the function succeeds, the return value is the number of characters stored into the buffer pointed to by lpBuffer, not including the terminating null character.

If the specified environment variable name was not found in the environment block for the current process, the return value is zero.

If the buffer pointed to by lpBuffer is not large enough, the return value is the buffer size, in characters, required to hold the value string and its terminating null character.

See Also

GetEnvironmentStrings, SetEnvironmentVariable


GetExceptionCode

The GetExceptionCode function retrieves a code that identifies the type of exception that occurred. The function can be called only from within the filter expression or exception-handler block of a try-except exception handler.

DWORD GetExceptionCode(VOID)

Parameters

This function has no parameters.

Return Value

The return value identifies the type of exception. Following are the exception codes likely to occur due to common programming errors:

Value	Meaning
EXCEPTION_ACCESS_VIOLATION
	The thread attempted to read from or write to a virtual address for which it does not have the appropriate access.
EXCEPTION_BREAKPOINT
	A breakpoint was encountered.
EXCEPTION_DATATYPE_MISALIGNMENT
	The thread attempted to read or write data that is misaligned on hardware that does not provide alignment. For example, 16-bit values must be aligned on 2-byte boundaries, 32-bit values on 4-byte boundaries, and so on.
EXCEPTION_SINGLE_STEP
	A trace trap or other single-instruction mechanism signaled that one instruction has been executed.
EXCEPTION_ARRAY_BOUNDS_EXCEEDED
	The thread attempted to access an array element that is out of bounds, and the underlying hardware supports bounds checking.
EXCEPTION_FLT_DENORMAL_OPERAND
	One of the operands in a floating-point operation is denormal. A denormal value is one that is too small to represent as a standard floating-point value.
EXCEPTION_FLT_DIVIDE_BY_ZERO
	The thread attempted to divide a floating-point value by a floating-point divisor of zero.
EXCEPTION_FLT_INEXACT_RESULT
	The result of a floating-point operation cannot be represented exactly as a decimal fraction.
EXCEPTION_FLT_INVALID_OPERATION
	This exception represents any floating-point exception not included in this list.
EXCEPTION_FLT_OVERFLOW
	The exponent of a floating-point operation is greater than the magnitude allowed by the corresponding type.
EXCEPTION_FLT_STACK_CHECK
	The stack overflowed or underflowed as the result of a floating-point operation.
EXCEPTION_FLT_UNDERFLOW
	The exponent of a floating-point operation is less than the magnitude allowed by the corresponding type.
EXCEPTION_INT_DIVIDE_BY_ZERO
	The thread attempted to divide an integer value by an integer divisor of zero.
EXCEPTION_INT_OVERFLOW
	The result of an integer operation caused a carry out of the most significant bit of the result.
EXCEPTION_PRIV_INSTRUCTION
	The thread attempted to execute an instruction whose operation is not allowed in the current machine mode.
EXCEPTION_NONCONTINUABLE_EXCEPTION
	The thread attempted to continue execution after a noncontinuable exception occurred.
Remarks

The GetExceptionCode function can be called only from within the filter expression or exception-handler block of a try-except statement. The filter expression is evaluated if an exception occurs during execution of the try block, and it determines whether the except block is executed. The following example shows the structure of a try-except statement.

try {

    /* try block */

}

except (filter-expression) {

    /* exception handler block */

}

The filter expression can invoke a filter function. The filter function cannot call GetExceptionCode. However, the return value of GetExceptionCode can be passed as a parameter to a filter function. The return value of the GetExceptionInformation function can also be passed as a parameter to a filter function. GetExceptionInformation returns a pointer to a structure that includes the exception-code information.

In the case of nested try-except statements, each statement's filter expression is evaluated until one is evaluated as EXCEPTION_EXECUTE_HANDLER or EXCEPTION_CONTINUE_EXECUTION. Each filter expression can invoke GetExceptionCode to get the exception code.

The exception code returned is the code generated by a hardware exception, or the code specified in the RaiseException function for a software-generated exception.

See Also

GetExceptionInformation, RaiseException


GetExceptionInformation

The GetExceptionInformation function retrieves a machine-independent description of an exception, and information about the machine state that existed for the thread when the exception occurred. This function can be called only from within the filter expression of a try-except exception handler.

LPEXCEPTION_POINTERS GetExceptionInformation(VOID)

Parameters

This function has no parameters.

Return Value

The return value is a pointer to an EXCEPTION_POINTERS structure that contains pointers to two other structures: an EXCEPTION_RECORD structure containing a description of the exception, and a CONTEXT structure containing the machine-state information.

Remarks

The filter expression (from which the function is called) is evaluated if an exception occurs during execution of the try block, and it determines whether the except block is executed. The following example shows the structure of a try-except statement.

try {

    /* try block */

}

except (filter-expression) {

    /* exception handler block */

}

The filter expression can invoke a filter function. The filter function cannot call GetExceptionInformation. However, the return value of GetExceptionInformation can be passed as a parameter to a filter function.

To pass the EXCEPTION_POINTERS information to the exception-handler block, the filter expression or filter function must copy the pointer or the data to safe storage that the handler can later access.

In the case of nested try-except statements, each statement's filter expression is evaluated until one is evaluated as EXCEPTION_EXECUTE_HANDLER or EXCEPTION_CONTINUE_EXECUTION. Each filter expression can invoke GetExceptionInformation to get exception information.

See Also

CONTEXT, EXCEPTION_POINTERS, EXCEPTION_RECORD, GetExceptionCode


GetExitCodeProcess

The GetExitCodeProcess function retrieves the termination status of the specified process.

BOOL GetExitCodeProcess(

HANDLE  hProcess,	// handle to the process
LPDWORD  lpExitCode	// address to receive termination status
);
Parameters

hProcess

Identifies the process. The handle must have PROCESS_QUERY_INFORMATION access.

lpExitCode

Points to a 32-bit variable to receive the process termination status.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the specified process has not terminated, the termination status returned is STILL_ACTIVE. If the process has terminated, the termination status returned may be one of the following:

•	The exit value specified in the ExitProcess or TerminateProcess function.

•	The return value from the main or WinMain function of the process.

•	The exception value for an unhandled exception that caused the process to terminate.

See Also

ExitProcess, ExitThread, TerminateProcess, WinMain


GetExitCodeThread

The GetExitCodeThread function retrieves the termination status of the specified thread.

BOOL GetExitCodeThread(

HANDLE  hThread,	// handle to the thread
LPDWORD  lpExitCode	// address to receive termination status
);
Parameters

hThread

Identifies the thread. The handle must have THREAD_QUERY_INFORMATION access.

lpExitCode

Points to a 32-bit variable to receive the thread termination status.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the specified thread has not terminated, the termination status returned is STILL_ACTIVE. If the thread has terminated, the termination status returned may be one of the following:

•	The exit value specified in the ExitThread or TerminateThread function.

•	The return value from the thread function.

•	The exit value of the thread's process.

See Also

ExitThread, GetExitCodeProcess, TerminateThread


GetExpandedName

The GetExpandedName function retrieves the original name of a compressed file, if the file was compressed by using the Microsoft File Compression Utility (COMPRESS.EXE) and the /r option was specified.

INT GetExpandedName(

LPTSTR  lpszSource,	// address of name of compressed file
LPTSTR  lpszBuffer	// address of buffer for original filename
);
Parameters

lpszSource

Points to a string that specifies the name of a compressed file.

lpszBuffer

Points to a buffer that receives the name of the compressed file.

Return Value

If the function succeeds, the return value is 1.

If the function fails, the return value is LZERROR_BADVALUE.

Note that GetExpandedName calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread's last-error code.

Remarks

The contents of the buffer pointed to by the lpszBuffer parameter is the original filename if the file was compressed by using the /r option. If the /r option was not used, this function duplicates the name in the lpszSource parameter into the lpszBuffer buffer.


GetFileAttributes

The GetFileAttributes function returns attributes for a specified file or directory.

DWORD GetFileAttributes(

LPCTSTR  lpFileName	// address of the name of a file or directory
);
Parameters

lpFileName

Points to a null-terminated string that specifies the name of a file or directory.

Windows NT

There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the GetFileAttributes function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) version of GetFileAttributes and prepending "\\?\" to the path. The "\\?\" tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with GetFileAttributesW. This also works with UNC names. The "\\?\" is ignored as part of the path. For example, "\\?\C:\myworld\private" is seen as "C:\myworld\private", and "\\?\UNC\bill_g_1\hotstuff\coolapps" is seen as "\\bill_g_1\hotstuff\coolapps".

Windows 95

The lpFileName string must not exceed MAX_PATH characters. Windows 95 does not support the "\\?\" prefix.

Return Value

If the function succeeds, the return value contains the attributes of the specified file or directory.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

The attributes can be one or more of the following values:

Value	Meaning
FILE_ATTRIBUTE_ARCHIVE	The file or directory is an archive file or directory. Applications use this flag to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED	The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY	The "file or directory" is a directory.
FILE_ATTRIBUTE_HIDDEN	The file or directory is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL	The file or directory has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_READONLY	The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.
FILE_ATTRIBUTE_SYSTEM	The file or directory is part of, or is used exclusively by, the operating system.
See Also

DeviceIOControl, FindFirstFile, FindNextFile, SetFileAttributes


GetFileInformationByHandle

The GetFileInformationByHandle function retrieves information about the specified file.

BOOL GetFileInformationByHandle(

HANDLE  hFile,	// handle of file
LPBY_HANDLE_FILE_INFORMATION  lpFileInformation,	// address of structure
);
Parameters

hFile

Identifies the file for which information is returned.

lpFileInformation

Points to a BY_HANDLE_FILE_INFORMATION structure that receives the file information. The structure can be used in subsequent calls to GetFileInformationByHandle to refer to the information about the file.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Depending on the underlying network components of the operating system and the type of server connected to, the GetFileInformationByHandle function may fail, return partial information, or full information for the given file. In general, you should not use GetFileInformationByHandle unless your application is intended to be run on a limited set of operating system configurations.

See Also

BY_HANDLE_FILE_INFORMATION


GetFileResource

The GetFileResource function is not implemented in the Win32 API.


GetFileResourceSize

The GetFileResourceSize function is is not implemented in the Win32 API.


GetFileSecurity

The GetFileSecurity function obtains specified information about the security of a file or directory. The information obtained is constrained by the caller's access rights and privileges.

BOOL GetFileSecurity(

LPCTSTR  lpFileName,	// address of string for file name
SECURITY_INFORMATION  RequestedInformation,	// requested information
PSECURITY_DESCRIPTOR  pSecurityDescriptor,	// address of security descriptor
DWORD  nLength,	// size of security descriptor buffer
LPDWORD  lpnLengthNeeded	// address of required size of buffer
);
Parameters

lpFileName

Points to a null-terminated string specifying the file or directory for which security information is retrieved.

RequestedInformation

Specifies a SECURITY_INFORMATION structure that identifies the security information being requested.

pSecurityDescriptor

Points to a buffer that receives a copy of the security descriptor of the object specified by the lpFileName parameter. The calling process must have the right to view the specified aspects of the object's security status. The SECURITY_DESCRIPTOR structure is returned in self-relative format.

nLength

Specifies the size, in bytes, of the buffer pointed to by the pSecurityDescriptor parameter.

lpnLengthNeeded

Points to a variable the function sets to zero if the file descriptor is copied successfully. If the buffer is too small for the security descriptor, this variable receives the number of bytes required. If this variable's value is greater than that of the nLength parameter when the function returns, none of the security descriptor is copied to the buffer.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetFileSecurity


GetFileSize

The GetFileSize function retrieves the size, in bytes, of the specified file.

DWORD GetFileSize(

HANDLE  hFile,	// handle of file to get size of
LPDWORD  lpFileSizeHigh,	// address of high-order word for file size
);
Parameters

hFile

Specifies an open handle of the file whose size is being returned. The handle must have been created with either GENERIC_READ or GENERIC_WRITE access to the file.

lpFileSizeHigh

Points to the variable where the high-order word of the file size is returned. This parameter can be NULL if the application does not require the high-order word.

Return Value

If the function succeeds, the return value is the low-order doubleword of the file size, and, if lpFileSizeHigh is non-NULL, the function puts the high-order doubleword of the file size into the variable pointed to by that parameter.

If the function fails and lpFileSizeHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

If the function fails and lpFileSizeHigh is non-NULL, the return value is 0xFFFFFFFF and GetLastError will return a value other than NO_ERROR.

Remarks

You cannot use the GetFileSize function with a handle of a nonseeking device such as a pipe or a communications device. To determine the file type for hFile, use the GetFileType function.

The GetFileSize function obtains the uncompressed size of a file. Use the GetCompressedFileSize function to obtain the compressed size of a file.

Note that if the return value is 0xFFFFFFFF and lpFileSizeHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed. The following sample code illustrates this point:

//

// Case One: calling the function with

//           lpFileSizeHigh == NULL

// Try to obtain hFile's size

dwSize = GetFileSize (hFile, NULL) ;

// If we failed ...

if (dwSize == 0xFFFFFFFF) {

    // Obtain the error code.

    dwError = GetLastError() ;

    // Deal with that failure.

    .

    .

    .

    } // End of error handler

//

// Case Two: calling the function with

//           lpFileSizeHigh != NULL

// Try to obtain hFile's huge size.

dwSizeLow = GetFileSize (hFile, & dwSizeHigh) ;

// If we failed ...

if (dwSizeLow == 0xFFFFFFFF

    &&

    (dwError = GetLastError()) != NO_ERROR ){

    // Deal with that failure.

    .

    .

    .

    } // End of error handler.

See Also

GetCompressedFileSize, GetFileType


GetFileTime

The GetFileTime function retrieves the date and time that a file was created, last accessed, and last modified.

BOOL GetFileTime(

HANDLE  hFile,	// identifies the file
LPFILETIME  lpCreationTime,	// address of creation time
LPFILETIME  lpLastAccessTime,	// address of last access time
LPFILETIME  lpLastWriteTime	// address of last write time
);
Parameters

hFile

Identifies the files for which to get dates and times. The file handle must have been created with GENERIC_READ access to the file.

lpCreationTime

Points to a FILETIME structure to receive the date and time the file was created. This parameter can be NULL if the application does not require this information.

lpLastAccessTime

Points to a FILETIME structure to receive the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or, in the case of executable files, run. This parameter can be NULL if the application does not require this information.

lpLastWriteTime

Points to a FILETIME structure to receive the date and time the file was last written to. This parameter can be NULL if the application does not require this information.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The FAT, NTFS, and HPFS file systems all support the file creation, last access, and last write time values.

See Also

FILETIME, GetFileSize, GetFileType, SetFileTime


GetFileTitle

The GetFileTitle function returns the name of the file identified by the lpszFile parameter.

short GetFileTitle(

LPCTSTR  lpszFile,	// address of full path and filename for file
LPTSTR  lpszTitle,	// address of buffer that receives filename
WORD  cbBuf	// length of buffer
);
Parameters

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.

Return Value

If the function succeeds, the return value is zero. If the filename is invalid, the return value is a negative number. If the buffer pointed to by the lpszTitle parameter is too small, the return value is a positive integer that specifies the required buffer size, in characters.

Remarks

GetFileTitle returns an error value if the buffer pointed to by the lpszFile parameter contains any of the following elements:

•	An empty string

•	A string containing a wildcard (*), opening bracket ([), or closing bracket (])

•	A string that ends with a colon (:), slash mark (/), or backslash (\)

•	A string whose length exceeded the length of the buffer

•	An invalid character (for example, a space or an unprintable character)

The required buffer size includes the terminating null character.

Note that sizes are specified and received as character counts, not bytes for UNICODE; the counts are valid for both the _A and _W versions of the function.

To get the buffer size needed for the name of a file, call the function with lpszTitle set to NULL and cbBuf set to zero. The function will return the required value.

Windows 95: On Windows 95, the GetFileTitle function retrieves the same text that the system would compose in displaying a filename to the user. This text is intended to be used for display purposes only and is in accordance with the user's preferences for display of filenames. There are two important implications of this enhancement. First, an application cannot expect to use the resultant text to call file system functions because it is merely a display name. Secondly, in preserving the function's "insufficient buffer" case, the return value for that codepath reflects the size of the text that would be composed in the normal case such that the caller may attempt to allocate sufficient storage and retrieve the result with a subsequent call to GetFileTitle. More generally, there is no guaranteed connection between the resultant text or return value and the characters in the original buffer passed by the application.

In porting applications to Windows 95, developers will need to update any code that relies on such behavior in previous versions of the operating system. The most common case is code that deliberately calls GetFileTitle with a NULL return buffer, passing size 0, and then uses the return value as an index into the original string. This technique is no longer supported. Applications can usually achieve similar results (and superior performance) with runtime library functions such as strrchr, wcsrchr, and _mbsrchr.

See Also

GetOpenFileName, GetSaveFileName


GetFileType

The GetFileType function returns the type of the specified file.

DWORD GetFileType(

HANDLE  hFile	// file handle
);
Parameters

hFile

Identifies an open file handle.

Return Value

The return value is one of the following values:

Value	Meaning
FILE_TYPE_UNKNOWN	The type of the specified file is unknown.
FILE_TYPE_DISK	The specified file is a disk file.
FILE_TYPE_CHAR	The specified file is a character file, typically an LPT device or a console.
FILE_TYPE_PIPE	The specified file is either a named or anonymous pipe.
See Also

GetFileSize, GetFileTime


GetFileVersionInfo

The GetFileVersionInfo function returns version information about a specified file.

As with other file installation functions, GetFileVersionInfo works only with Win32 file images. It does not work with 16-bit Windows file images.

BOOL GetFileVersionInfo(

LPTSTR  lptstrFilename,	// pointer to filename string
DWORD  dwHandle,	// ignored
DWORD  dwLen,	// size of buffer
LPVOID  lpData	// pointer to buffer to receive file-version info.
);
Parameters

lptstrFilename

Pointer to a null-terminated filename string that specifies the file of interest.

dwHandle

This parameter is ignored.

dwLen

Specifies the size, in bytes, of the buffer pointed to by lpData.

Call the GetFileVersionInfoSize function to determine the size in bytes of a file's version information. dwLen should be equal to or greater than that value.

If the buffer pointed to by lpData is not large enough, the function truncates the file's-version information to the size of the buffer.

lpData

Pointer to a buffer to receive file-version information.

You can use this value in a subsequent call to the VerQueryValue function.

The file version information is always in Unicode format.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetFileVersionInfoSize, VerQueryValue, VS_VERSION_INFO


GetFileVersionInfoSize

The GetFileVersionInfoSize function determines whether the operating system can obtain version information about a specified file. If version information is available, GetFileVersionInfoSize returns the size in bytes of that information.

As with other file installation functions, GetFileVersionInfo works only with Win32 file images. It does not work with 16-bit Windows file images.

DWORD GetFileVersionInfoSize(

LPTSTR  lptstrFilename,	// pointer to filename string
LPDWORD  lpdwHandle	// pointer to variable to receive zero
);
Parameters

lptstrFilename

Pointer to a null-terminated filename string that specifies the file of interest.

lpdwHandle

Pointer to a variable that the function sets to zero.

Return Value

If the function succeeds, the return value is the size in bytes of the file's version information.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Call the GetFileVersionInfoSize function before calling the GetFileVersionInfo function.

See Also

GetFileVersionInfo, VerQueryValue


GetFocus

The GetFocus function retrieves the handle of the keyboard focus window associated with the thread that called the function.

HWND GetFocus(VOID)

Parameters

This function has no parameters.

Return Value

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.

Remarks

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


GetFontData

The GetFontData function retrieves font metric data for a TrueType font.

DWORD GetFontData(

HDC  hdc,	// handle of device context
DWORD  dwTable,	// metric table to query
DWORD  dwOffset,	// offset into table being queried
LPVOID  lpvBuffer,	// address of buffer for returned data
DWORD  cbData	// length of data to query
);
Parameters

hdc

Identifies the device context.

dwTable

Specifies the name of a font metric table from which the font data is to be retrieved. This parameter can identify one of the metric tables documented in the TrueType Font Files specification published by Microsoft Corporation. If this parameter is zero, the information is retrieved starting at the beginning of the font file.

dwOffset

Specifies the offset from the beginning of the font metric table to the location where the function should begin retrieving information. If this parameter is zero, the information is retrieved starting at the beginning of the table specified by the dwTable parameter. If this value is greater than or equal to the size of the table, an error occurs.

lpvBuffer

Points to a buffer to receive the font information. If this parameter is NULL, the function returns the size of the buffer required for the font data.

cbData

Specifies the length, in bytes, of the information to be retrieved. If this parameter is zero, GetFontData returns the size of the data specified in the dwTable parameter.

Return Value

If the function succeeds, the return value is the number of bytes returned.

If the function fails, the return value is GDI_ERROR.

Remarks

An application can sometimes use the GetFontData function to save a TrueType font with a document. To do this, the application determines whether the font can be embedded by checking the otmfsType member of the OUTLINETEXTMETRIC structure. If bit 1 of otmfsType is set, embedding is not permitted for the font. If bit 1 is clear, the font can be embedded. If bit 2 is set, the embedding is read-only. If embedding is permitted, the application can retrieve the entire font file, specifying zero for the dwTable, dwOffset, and cbData parameters.

If an application attempts to use this function to retrieve information for a non-TrueType font, an error occurs.

See Also

GetTextMetrics, OUTLINETEXTMETRIC


GetFontLanguageInfo  (preliminaryWindows 95)
GetFontLanguageInfo  (preliminary−Windows 95)

The GetFontLanguageInfo function returns information about the currently selected font for the given display context. Applications typically use this information and the GetCharacterPlacement function to prepare a character string for display.

DWORD GetFontLanguageInfo(

HDC hdc	// handle of device context
);
Parameters

hdc

Handle of a display context.

Return Value

The return value identifies characteristics of the currently selected font. The function returns 0 if the font is "normalized" and can be treated as a simple Latin font; it returns GCP_ERROR if an error occurs. Otherwise, the function returns a combination of the following values:

Value	Meaning
FLI_GLYPHS	The font contains extra glyphs not normally accessible using the codepage. Use GetCharacterPlacement to access the glyphs. This value is for information only and is not intended to be passed to GetCharacterPlacement.
GCP_LIGATE	The font contains ligation glyphs which can be substituted for specific character combinations.
GCP_USEKERNING	The font contains a kerning table which can be used to provide better spacing between the characters and glyphs.
GCP_DBCS	The character set is DBCS.
GCP_REORDER	The font covers characters which require reordering for display. For example Hebrew or Arabic.
GCP_DIACRITIC	The font contains diacritic glyphs
GCP_GLYPHSHAPE	The font contains multiple glyphs per code point or per code point combination (supports shaping and/or ligation), and the font contains advanced glyph tables to provide extra glyphs for the extra shapes. This is especially useful in languages such as Semitic and DBCS languages. If this value is given, the lpGlyphs array should be used with the GetCharacterPlacement function and the ETO_GLYPHINDEX value needs to be passed to the ExtTextOut function when the string is drawn.
GCP_KASHIDA	The font (and language) permit Kashidas.
The return value, when masked with FLI_MASK, can be passed directly to the GetCharacterPlacement function.

See Also

ExtTextOut, GetCharacterPlacement


GetForegroundWindow

The GetForegroundWindow function returns the handle of the foreground window (the window with which the user is currently working). The system assigns a slightly higher priority to the thread that creates the foreground window than it does to other threads.

HWND GetForegroundWindow(VOID)

Parameters

This function has no parameters.

Return Value

The return value is the handle of the foreground window.

See Also

SetForegroundWindow


GetForm

The GetForm function initializes a FORM_INFO_1 structure with data describing the specified form for a printer.

BOOL GetForm(

HANDLE  hPrinter,	// handle of printer
LPTSTR  pFormName,	// address of form name
DWORD  Level,	// structure level
LPBYTE  pForm,	// address of structure array
DWORD  cbBuf,	// count of bytes in array
LPDWORD  pcbNeeded	// addr. of variable with count of bytes retrieved (or required)
);
Parameters

hPrinter

Identifies the printer.

pFormName

Points to a null-terminated string that specifies the name of the form.

Level

Specifies the version of the structure to which pForm points. This value must be 1.

pForm

Points to an array of bytes that receives the initialized FORM_INFO_1 structure.

cbBuf

Specifies the size, in bytes, of the pForm array.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The printer handle hPrinter is obtained by calling the OpenPrinter function.

See Also

AddForm, DeleteForm, OpenPrinter


GetFreeSpace

The GetFreeSpace function is obsolete. It is provided to simplify porting of 16-bit Windows-based applications. Win32-based applications should use the GlobalMemoryStatus function.

DWORD GetFreeSpace(     WORD  w	// amount of free space
);


GetFullPathName

The GetFullPathName function retrieves the full path and filename of a specified file.

DWORD GetFullPathName(

LPCTSTR  lpFileName,	// address of name of file to find path for
DWORD  nBufferLength,	// size, in characters, of path buffer
LPTSTR  lpBuffer,	// address of path buffer
LPTSTR  *lpFilePart	// address of filename in path
);
Parameters

lpFileName

Points to a null-terminated string that specifies a valid filename.

nBufferLength

Specifies the size, in characters, of the buffer for the drive and path.

lpBuffer

Points to a buffer that contains the null-terminated string for the name of the drive and path.

lpFilePart

Points to a variable that receives the address (in lpBuffer) of the final filename component in the path.

Return Value

If the GetFullPathName function succeeds, the return value is the length, in characters, of the string copied to lpBuffer, not including the terminating null character.

If the lpBuffer buffer is too small, the return value is the size of the buffer, in characters, required to hold the path.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetFullPathName function merges the name of the current drive and directory with the specified filename to determine the full path and filename of the specified file. It also calculates the address of the filename portion of the full path and filename. This function does not verify that the resulting path and filename are valid or that they refer to an existing file on the associated volume.

See Also

GetShortPathName, GetTempPath, SearchPath


GetGlyphOutline

The GetGlyphOutline function retrieves the outline or bitmap for a character in the TrueType font that is selected into the specified device context.

DWORD GetGlyphOutline(

HDC  hdc,	// handle of device context
UINT  uChar,	// character to query
UINT  uFormat,	// format of data to return
LPGLYPHMETRICS  lpgm,	// address of structure for metrics
DWORD  cbBuffer,	// size of buffer for data
LPVOID  lpvBuffer,	// address of buffer for data
CONST MAT2 *  lpmat2	// address of transformation matrix structure
);
Parameters

hdc

Identifies the device context.

uChar

Specifies the character for which data is to be returned.

uFormat

Specifies the format 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 Remarks 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 following Return Value section.
lpgm

Points to the GLYPHMETRICS structure describing the placement of the glyph in the character cell.

cbBuffer

Specifies the size of the buffer where the function is to copy information about the outline character. If this value is zero, the function returns the required size of the buffer.

lpvBuffer

Points to the buffer where the function is to copy information about the outline character. If this value is NULL, the function returns the required size of the buffer.

lpmat2

Points to a MAT2 structure specifying a transformation matrix for the character.

Return Value

If GGO_BITMAP or GGO_NATIVE is specified, and the function succeeds, the return value is greater than zero; otherwise, the return value is GDI_ERROR. If one of these flags is specified, and the buffer size or address is zero, the return value specifies the required buffer size, in bytes.

If GGO_METRICS is specified, and the function fails, the return value is GDI_ERROR.

Remarks

The glyph outline returned by the GetGlyphOutline function is for a grid-fitted glyph. (A grid-fitted glyph is a glyph that has been modified so that its bitmapped image conforms as closely as possible to the original design of the glyph.) If an application needs an unmodified glyph outline, it can request the glyph outline for a character in a font whose size is equal to the font's em unit. The value for a font's em unit is stored in the otmEMSquare member of the OUTLINETEXTMETRIC structure.

The glyph bitmap returned by the GetGlyphOutline function when GGO_BITMAP is specified is a doubleword-aligned, row-oriented monochrome bitmap.

An application can rotate characters retrieved in bitmap format by specifying a 2-by-2 transformation matrix in the lpMatrix parameter.

See Also

FORM_INFO_1, GetOutlineTextMetrics, GLYPHMETRICS, MAT2, OUTLINETEXTMETRIC, POINT


GetGraphicsMode

The GetGraphicsMode function retrieves the current graphics mode for the specified device context.

int GetGraphicsMode(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value is the current graphics mode. It can be one of the following values:

Value	Meaning
GM_COMPATIBLE	The current graphics mode is the compatible graphics mode, a mode that is compatible with Windows version 3.1. In this graphics mode, an application cannot set or modify the world transformation for the specified device context. The compatible graphics mode is the default graphics mode.
GM_ADVANCED	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.

Remarks

An application can set the graphics mode for a device context by calling the SetGraphicsMode function.

See Also

SetGraphicsMode


GetHandleInformation  (preliminaryWindows NT)
GetHandleInformation  (preliminary−Windows NT)

The GetHandleInformation function obtains information about certain properties of an object handle. The information is obtained as a set of bit flags.

BOOL GetHandleInformation (

HANDLE  hObject,	// handle to an object
LPDWORD  lpdwFlags	// points to variable to receive flags
);
Parameters

hObject

Specifies a handle to an object. The GetHandleInformation function obtains information about this object handle.

lpdwFlags

Points to a variable to receive a set of bit flags that specify properties of the object handle. The following flags are defined:

Value	Meaning
HANDLE_FLAG_INHERIT	If this flag is set, a child process created with the bInheritHandles parameter of CreateProcess set to TRUE will inherit the object handle.
HANDLE_FLAG_PROTECT_FROM_CLOSE	If this flag is set, calling the CloseHandle function will not close the object handle.
Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CloseHandle, CreateProcess, SetHandleInformation


gethostbyadd  [image] r

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

struct hostent FAR * gethostbyaddr (

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

addr

A pointer to an address in network byte order.

len

The length of the address, which must be 4 for PF_INET addresses.

type

The type of the address, which must be PF_INET.

Return Value

If the function succeeds, gethostbyaddr returns a pointer to the hostent structure previously described.

If the function fails, it returns a NULL pointer. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
Remarks

The gethostbyaddr function returns a pointer to the following structure, which contains the name(s) and address which correspond to the specified address.

struct hostent {

    char FAR *       h_name;

    char FAR * FAR * h_aliases;

    short            h_addrtype;

    short            h_length;

    char FAR * FAR * h_addr_list;

};

The members of this structure are:

Member	Usage
h_name	Official name of the host (PC).
h_aliases	A NULL-terminated array of alternate names.
h_addrtype	The type of address being returned; for Windows Sockets this is always PF_INET.
h_length	The length, in bytes, of each address; for PF_INET, this is always 4.
h_addr_list	A NULL-terminated list of addresses for the host. Addresses are returned in network byte order.
The macro h_addr is defined to be h_addr_list[0] for compatibility with older software.

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

See Also

gethostbyname, WSAAsyncGetHostByAddr, WSACancelBlockingCall, WSAStartup


gethostbynam  [image] e

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

struct hostent FAR * gethostbyname (

const char FAR * name
);
Parameters

name

A pointer to the name of the host.

Return Value

If the function succeeds, gethostbyname returns a pointer to the hostent structure described above.

If the function fails, it returns a NULL pointer. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
Remarks

The gethostbyname function returns a pointer to a hostent structure as described under gethostbyaddr. The contents of this structure correspond to the host name name.

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

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

See Also

gethostbyaddr, inet_addr, WSAAsyncGetHostByName, WSACancelBlockingCall, WSAStartup


gethostname

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

int PASCAL FAR gethostname (

char FAR * name,
int namelen
);
Parameters

name

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

namelen

The length of the buffer.

Return Value

If the function succeeds, gethostname returns zero.

If the function fails, it returns SOCKET_ERROR. To get extended error information, call WSAGetLastError.

Error Codes

WSAEFAULT	The namelen parameter is too small.
WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
Remarks

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

See Also

gethostbyname, WSAAsyncGetHostByName, WSAStartup


GetICMProfile  (preliminaryWindows 95)
GetICMProfile  (preliminary−Windows 95)

The GetICMProfile function retrieves the name of the color profile file for the device associated with the specified device context.

BOOL GetICMProfile(

HDC  hdc,
DWORD  cbName,
LPTSTR  lpszFilename
);
Parameters

hdc

Handle to the device context.

cbName

Size, in bytes or characters, of the buffer that receives the filename, depending on whether the ANSI or Unicode version of the function is used.

lpszFilename

Pointer to the buffer that receives the null-terminated string specifying the full path of the color profile file.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

GetICMProfile fails if image color matching has not been enabled for the specified device context.


GetIconInfo

The GetIconInfo function retrieves information about the specified icon or cursor.

BOOL GetIconInfo(

HICON  hIcon,	// icon handle
PICONINFO  piconinfo	// address of icon structure
);
Parameters

hIcon

Identifies the icon or cursor. To retrieve information about a standard icon or cursor, specify one of the following values:

Value	Meaning
IDC_ARROW	Arrow cursor
IDC_IBEAM	I-beam cursor
IDC_WAIT	Hourglass cursor
IDC_CROSS	Crosshair cursor
IDC_UPARROW	Up arrow cursor
IDC_SIZENWSE	Sizing cursor, points northwest and southeast
IDC_SIZENESW	Sizeing cursor, points northeast and southwest
IDC_SIZEWE	Sizing cursor, points west and east
IDC_SIZENS	Sizing cursor, points north and south
IDC_SIZEALL	Sizing cursor, points north, south, east, and west
IDC_NO	"No" cursor
IDC_APPSTARTING	Application-starting cursor (arrow and hourglass)
IDC_HELP	Help cursor (arrow and question mark)
IDI_APPLICATION	Application icon
IDI_HAND	Stop sign icon
IDI_QUESTION	Question-mark icon
IDI_EXCLAMATION	Exclamation point icon
IDI_ASTERISK	Asterisk icon (letter "i" in a circle)
IDI_WINLOGO	Windows logo icon
piconinfo

Points to an ICONINFO structure. The function fills in the structure's members.

Return Value

If the function succeeds, the return value is TRUE and the function fills in the members of the specified ICONINFO structure.

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

Remarks

GetIconInfo creates bitmaps for the hbmMask and hbmColor members of ICONINFO. The calling application must manage these bitmaps and delete them when they are no longer necessary.

See Also

CreateIcon, CreateIconFromResource, CreateIconIndirect, DestroyIcon, DrawIcon, DrawIconEx, ICONINFO, LoadIcon, LookupIconIdFromDirectory


GetInputState

The GetInputState function determines whether there are mouse-button or keyboard messages in the calling thread's message queue.

BOOL GetInputState(VOID)

Parameters

This function has no parameters.

Return Value

If the queue contains one or more new mouse-button or keyboard messages, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

GetQueueStatus


GetInstanceData

The GetInstanceData function is not implemented in the Win32 API. Each Win32-based application runs in its own address space.


GetJob

The GetJob function retrieves print-job data for the specified printer.

BOOL GetJob(

HANDLE  hPrinter,	// handle of printer
DWORD  JobId,	// job identifier value
DWORD  Level,	// data-structure level
LPBYTE  pJob,	// address of data-structure array
DWORD  cbBuf,	// count of bytes in array
LPDWORD  pcbNeeded	// address of value that contains count of bytes retrieved (or required)
);
Parameters

hPrinter

Identifies the printer for which the print-job data is retrieved.

JobId

Identifies the print job for which data should be retrieved.

Level

Specifies the level of the structure to which pJob points. This value must be either 1 or 2.

pJob

Points to an array that contains either a JOB_INFO_1 or a JOB_INFO_2 structure. If Level is 1, this function stores the data in a JOB_INFO_1 structure; if Level is 2, this function stores the data in a JOB_INFO_2 structure.

cbBuf

Specifies the size, in bytes, of the array.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AddJob, JOB_INFO_1, JOB_INFO_2, ScheduleJob, SetJob


GetKBCodePage

The GetKBCodePage function is provided for compatibility with earlier versions of Windows. In the Win32 application programming interface (API) it just calls the GetOEMCP function. New applications should use the GetOEMCP function.

UINT GetKBCodePage(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is an OEM code-page identifier, or it is the default identifier if the registry value is not readable. For a list of OEM code-page identifiers, see GetOEMCP.

See Also

GetACP, GetOEMCP


GetKernelObjectSecurity

The GetKernelObjectSecurity function retrieves a copy of the security descriptor protecting a kernel object.

BOOL GetKernelObjectSecurity(

HANDLE  Handle,	// handle of object to query
SECURITY_INFORMATION  RequestedInformation,	// requested information
PSECURITY_DESCRIPTOR  pSecurityDescriptor,	// address of security descriptor
DWORD  nLength,	// size of buffer for security descriptor
LPDWORD  lpnLengthNeeded	// address of required size of buffer
);
Parameters

Handle

Identifies a kernel object.

RequestedInformation

Specifies a SECURITY_INFORMATION structure that identifies the security information being requested.

pSecurityDescriptor

Points to a buffer the function fills with a copy of the security descriptor of the specified object. The calling process must have the right to view the specified aspects of the object's security status. The SECURITY_DESCRIPTOR structure is returned in self-relative format.

nLength

Specifies the size, in bytes, of the buffer pointed to by the pSecurityDescriptor parameter.

lpnLengthNeeded

Points to a variable the function sets to zero if the descriptor is copied successfully. If the buffer is too small for the security descriptor, this variable receives the number of bytes required. If this variable's value is greater than the value of the nLength parameter when the function returns, none of the security descriptor is copied to the buffer.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

To read the kernel object's security descriptor, the calling process must be either granted READ_CONTROL access or be the object's owner. In addition, the calling process must have the SE_SECURITY_NAME privilege to read the system access-control list.

See Also

GetFileSecurity, GetPrivateObjectSecurity, GetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetKernelObjectSecurity


GetKerningPairs

The GetKerningPairs function retrieves the character-kerning pairs for the currently selected font for the specified device context.

DWORD GetKerningPairs(

HDC  hdc,	// handle of device context
DWORD  nNumPairs,	// number of kerning-pairs to be retrieved
LPKERNINGPAIR  lpkrnpair	// address of kerning-pair array
);
Parameters

hdc

Identifies the device context.

nNumPairs

Specifies the number of pairs that fit in the lpkrnpair array. If the font has more than nNumPairs kerning pairs, an error is returned.

lpkrnpair

Points to an array of KERNINGPAIR structures to receive the kerning pairs. The array must contain at least as many structures as specified by the nNumPairs parameter. If this parameter is NULL, the function returns the total number of kerning pairs for the font.

Return Value

If the function succeeds, the return value is the number of kerning pairs returned.

If the function fails, the return value is zero.

See Also

KERNINGPAIR


GetKeyboardLayout  (preliminaryWindows 95)
GetKeyboardLayout  (preliminary−Windows 95)

The GetKeyboardLayout function retrieves the active layout for the specified thread. If the dwLayout parameter is zero, the layout for the active thread is returned.

HKL GetKeyboardLayout(

DWORD dwLayout	// thread identifier
);
Parameters

dwLayout

Identifies the thread to query or is zero for the current thread.

Return Value

The return value is the keyboard layout handle for the thread. The low word contains a locale identifier identifying the input language and the high word contains a device handle identifying the physical layout of the keyboard.

See Also

ActivateKeyboardLayout, CreateThread, LoadKeyboardLayout


GetKeyboardLayoutList  (preliminaryWindows 95)
GetKeyboardLayoutList  (preliminary−Windows 95)

The GetKeyboardLayoutList function retrieves the keyboard layout handles corresponding to the current set of input locales in the system. The function copies the handles to the given buffer.

UINT GetKeyboardLayoutList(

int nBuff,	// size of buffer in array element
HKL FAR * lpList	// buffer for keyboard layout handles
);
Parameters

nBuff

Specifies the maximum number of handles that the buffer can hold.

lpList

Points to the buffer, an array, that receives the keyboard layout handles.

Return Value

If the function succeeds, the return value is the number of layout handles copied to the buffer or, if nBuff is zero, the return value is the size, in array elements, of the buffer needed to receive all current layout handles.

See Also

GetKeyboardLayout


GetKeyboardLayoutName

The GetKeyboardLayoutName function retrieves the name of the active keyboard layout.

BOOL GetKeyboardLayoutName(

LPTSTR  pwszKLID	// address of buffer for layout name
);
Parameters

pwszKLID

Points to the buffer of at least KL_NAMELENGTH characters that is to receive the name of the keyboard layout, including the NULL terminator. This will be a copy of the string provided to the LoadKeyboardLayout function, unless layout substitution took place.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

ActivateKeyboardLayout, LoadKeyboardLayout, UnloadKeyboardLayout


GetKeyboardState

The GetKeyboardState function copies the status of the 256 virtual keys to the specified buffer.

BOOL GetKeyboardState(

PBYTE  lpKeyState	// address of array to receive status data
);
Parameters

lpKeyState

Points to the 256-byte array that will receive the status data for each virtual key.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application can call this function to retrieve the current status of all the virtual keys. The status changes as a thread removes keyboard messages from its message queue. The status does not change as keyboard messages are posted to the message queue.

When the function returns, each member of the array pointed to by the lpKeyState parameter contains status data for a virtual key. If the high-order bit is 1, the key is down; otherwise, it is up. If the low-order bit is 1, the key is toggled. A key, such as the CAPS LOCK key, is toggled if it is turned on. The key is off and untoggled if the low-order bit is 0. A toggle key's indicator light (if any) on the keyboard will be on when the key is toggled, and off when the key is untoggled.

To retrieve status information for an individual key, use the GetKeyState function.

An application can use the virtual-key code constants VK_SHIFT, VK_CONTROL and VK_MENU as indices into the array pointed to by lpKeyState. This gives the status of the SHIFT, CTRL, or ALT keys without distinguishing between left and right. An application can also use the following virtual-key code constants as indices to distinguish between the left and right instances of those keys:

VK_LSHIFT	VK_RSHIFT
VK_LCONTROL	VK_RCONTROL
VK_LMENU	VK_RMENU
These left- and right-distinguishing constants are available to an application only through the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

See Also

GetKeyState, GetAsyncKeyState, MapVirtualKey, SetKeyboardState


GetKeyboardType

The GetKeyboardType function retrieves information about the current keyboard.

int GetKeyboardType(

int  nTypeFlag	// type of information to retrieve
);
Parameters

nTypeFlag

Specifies the type of keyboard information to be retrieved. This parameter can be one of the following values:

Value	Meaning
0	Keyboard type
1	Keyboard subtype
2	Number of function keys on the keyboard
Return Value

If the function succeeds, the return value specifies the requested information.

If the function fails, the return value is zero.

Remarks

The subtype is an original equipment manufacturer (OEM)-dependent value. The type may be one of the following values:

Value	Meaning
1	IBM® PC/XT® ( ) or compatible (83-key) keyboard
2	Olivetti® "ICO" (102-key) keyboard
3	IBM PC/AT® (84-key) or similar keyboard
4	IBM enhanced (101- or 102-key) keyboard
5	Nokia® 1050 and similar keyboards
6	Nokia 9140 and similar keyboards
7	Japanese keyboard
The application can also determine the number of function keys on a keyboard from the keyboard type. Following are the number of function keys for each keyboard type:

Type	Number of function keys
1	10
2	12 (sometimes 18)
3	10
4	12
5	10
6	24
7	Hardware dependent and specified by the OEM


GetKeyNameText

The GetKeyNameText function retrieves a string that represents the name of a key.

int GetKeyNameText(

LONG  lParam,	// second parameter of keyboard message
LPTSTR  lpString,	// address of buffer for key name
int  nSize	// maximum length of key-name string length
);
Parameters

lParam

Specifies the second parameter of the keyboard message (such as WM_KEYDOWN) to be processed. The function interprets the following portions of lParam:

Bits	Meaning
16−23	Scan code.
24	Extended-key flag. Distinguishes some keys on an enhanced keyboard.
25	"Don't care" bit. The application calling this function sets this bit to indicate that the function should not distinguish between left and right CTRL and SHIFT keys, for example.
lpString

Points to a buffer that will receive the key name.

nSize

Specifies the maximum length, in characters, of the key name, including the terminating null character. (This parameter should be equal to the size of the buffer pointed to by the lpString parameter.)

Return Value

If the function succeeds, a null-terminated string is copied into the specified buffer, and the return value is the length of the string, in characters, not counting the terminating null character.

Remarks

The format of the key-name string depends on the current keyboard layout. The keyboard driver maintains a list of names in the form of character strings for keys with names longer than a single character. The key name is translated according to the layout of the currently installed keyboard. The name of a character key is the character itself. The names of dead keys are spelled out in full.


GetKeyState

The GetKeyState function retrieves the status of the specified virtual key. The status specifies whether the key is up, down, or toggled (on, off — alternating each time the key is pressed).

SHORT GetKeyState(

int  nVirtKey	// virtual-key code
);
Parameters

nVirtKey

Specifies a virtual key. If the desired virtual key is a letter or digit (A through Z, a through z, or 0 through 9), nVirtKey must be set to the ASCII value of that character. For other keys, it must be a virtual-key code.

If a non-English keyboard layout is used, virtual keys with values in the range ASCII A through Z and 0 through 9 are used to specify most of the character keys. For example, for the German keyboard layout, the virtual key of value ASCII O (0x4F) refers to the "o" key, whereas VK_OEM_1 refers to the "o with umlaut" key.

Return Value

If the function succeeds, the return value specifies the status of the given virtual key. If the high-order bit is 1, the key is down; otherwise, it is up. If the low-order bit is 1, the key is toggled. A key, such as the CAPS LOCK key, is toggled if it is turned on. The key is off and untoggled if the low-order bit is 0. A toggle key's indicator light (if any) on the keyboard will be on when the key is toggled, and off when the key is untoggled.

Remarks

The key status returned from this function changes as a given thread reads key messages from its message queue. The status does not reflect the interrupt-level state associated with the hardware. Use the GetAsyncKeyState function to retrieve that information.

An application calls GetKeyState in response to a keyboard-input message. This function retrieves the state of the key when the input message was generated.

To retrieve state information for all the virtual keys, use the GetKeyboardState function.

An application can use the virtual-key code constants VK_SHIFT, VK_CONTROL, and VK_MENU as values for the nVirtKey parameter. This gives the status of the SHIFT, CTRL, or ALT keys without distinguishing between left and right. An application can also use the following virtual-key code constants as values for nVirtKey to distinguish between the left and right instances of those keys:

VK_LSHIFT	VK_RSHIFT
VK_LCONTROL	VK_RCONTROL
VK_LMENU	VK_RMENU
These left- and right-distinguishing constants are available to an application only through the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

See Also

GetAsyncKeyState, GetKeyboardState, MapVirtualKey, SetKeyboardState


GetLargestConsoleWindowSize

The GetLargestConsoleWindowSize function returns the size of the largest possible console window, based on the current font and the size of the display.

COORD GetLargestConsoleWindowSize(

HANDLE  hConsoleOutput	// handle of console screen buffer
);
Parameters

hConsoleOutput

Identifies a console screen buffer.

Return Value

If the function succeeds, the return value is a COORD structure that specifies the number of character cell rows (X member) and columns (Y member) in the largest possible console window. Otherwise, the members of the structure are zero.

To get extended error information, call GetLastError.

Remarks

The function does not take into consideration the size of the screen buffer, which means that the window size returned may be larger than the size of the screen buffer. The GetConsoleScreenBufferInfo function can be used to determine the maximum size of the console window, given the current screen buffer size, the current font, and the display size.

See Also

COORD, GetConsoleScreenBufferInfo, SetConsoleWindowInfo


GetLastActivePopup

The GetLastActivePopup function determines which pop-up window owned by the specified window was most recently active.

HWND GetLastActivePopup(

HWND  hWnd	// handle of owner window
);
Parameters

hWnd

Identifies the owner window.

Return Value

The return value identifies the most recently active pop-up window. The return value is the same as the hWnd parameter, if any of the following conditions are met:

•	The window identified by hWnd was most recently active.

•	The window identified by hWnd does not own any pop-up windows.

•	The window identified by hWnd is not a top-level window or it is owned by another window.

See Also

AnyPopup, ShowOwnedPopups


GetLastError

The GetLastError function returns the calling thread's last-error code value.

Most Win32 functions set their calling thread's last-error value when they fail; a few functions set it when they succeed.

DWORD GetLastError(VOID)

Parameters

This function has no parameters.

Return Value

The return value is the calling thread's last-error code value. Functions set this value by calling the SetLastError function. The Return Value section of each Win32 function's reference page notes the conditions under which the function sets the last-error code.

Remarks

You should call the GetLastError function immediately when a function's return value indicates that such a call will return useful data. That is because some functions call SetLastError(0) when they succeed, wiping out the error code set by the most recently failed function.

As noted, most Win32 functions call SetLastError when they fail. Function failure is typically indicated by a return value error code such as FALSE, NULL, 0xFFFFFFFF, or −1. Some functions call SetLastError under conditions of success; those cases are noted in each function's reference page.

Note that the last-error code is maintained on a per-thread basis. Multiple threads do not overwrite each other's last-error code.

Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no Win32 error code has this bit set. If you are defining an error code for your application, set this bit to one. That indicates that the error code has been defined by an application, and ensures that your error code does not conflict with any error codes defined by the operating system.

See Also

SetLastError, SetLastErrorEx


GetLengthSid

The GetLengthSid function returns the length, in bytes, of a valid SID structure. A SID is a security identifier.

DWORD GetLengthSid(

PSID  pSid	// address of SID to query
);
Parameters

pSid

Points to the SID structure whose length is returned. The structure is assumed to be valid.

Return Value

If the function succeeds, the return value is the length, in bytes, of the SID structure. If the SID structure is not valid, the return value is undefined. To get extended error information, call GetLastError.

See Also

GetSidLengthRequired, GetSidSubAuthorityCount, IsValidSid, SID


GetLocaleInfo

The GetLocaleInfo function retrieves information about a locale.

int GetLocaleInfo(

LCID  Locale,	// locale identifier
LCTYPE  LCType,	// type of information
LPTSTR  lpLCData,	// address of buffer for information
int  cchData	// size of buffer
);
Parameters

Locale

Specifies the locale to retrieve information for. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
LCType

Specifies one of the LCTYPE constants to indicate the type of information to be retrieved.

All LCTYPE values are mutually exclusive, with the exception of LOCALE_NOUSEROVERRIDE. An application may use the binary-OR operator to combine LOCALE_NOUSEROVERRIDE with any other LCTYPE value. If passed such an LCType value, the function bypasses user overrides, and returns the system default value for the requested LCID.

lpLCData

Points to a buffer to receive the requested data.

cchData

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpLCData buffer. If cchData is zero, the function returns the number of bytes or characters required to hold the information, and the buffer pointed to by lpLCData is not used.

Return Value

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the destination buffer, or if the cchData parameter is zero, the number of bytes or characters required to hold the locale information.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

The GetLocaleInfo function always retrieves information in text format. If the information is a numeric value, the function converts the number to text using decimal notation.

See Also

GetStringTypeA, GetStringTypeEx, GetStringTypeW, GetSystemDefaultLCID, GetUserDefaultLCID, MAKELCID


GetLocalTime

The GetLocalTime function retrieves the current local date and time.

VOID GetLocalTime(

LPSYSTEMTIME  lpSystemTime	// address of system time structure
);
Parameters

lpSystemTime

Points to a SYSTEMTIME structure to receive the current local date and time.

Return Value

This function does not return a value.

See Also

GetSystemTime, SetLocalTime, SYSTEMTIME


GetLogColorSpace  (preliminaryWindows 95)
GetLogColorSpace  (preliminary−Windows 95)

The GetLogColorSpace function retrieves information about the logical color space identified by the specified handle.

BOOL GetLogColorSpace(

HLOGCOLORSPACE  hColorSpace,
LPLOGCOLORSPACE  lpbuffer,
DWORD  nSize
);
Parameters

hColorSpace

Handle to the logical color space.

lpBuffer

Pointer to the LOGCOLORSPACE structure that receives the logical color space information.

nSize

Maximum size of the buffer in bytes.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

GetLogColorSpace copies as much information to the buffer as space allows. To determine the correct size of the buffer to use, applications should check the lcsSize member in the structure.

See Also

LOGCOLORSPACE


GetLogicalDrives

The GetLogicalDrives function returns a bitmask representing the currently available disk drives.

DWORD GetLogicalDrives(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is a bitmask representing the currently available disk drives. Bit position 0 (the least-significant bit) is drive A, bit position 1 is drive B, bit position 2 is drive C, and so on.

If the function fails, the return value is zero.

See Also

GetLogicalDriveStrings


GetLogicalDriveStrings

The GetLogicalDriveStrings function fills a buffer with strings that specify valid drives in the system.

DWORD GetLogicalDriveStrings(

DWORD  nBufferLength,	// size of buffer
LPTSTR  lpBuffer	// address of buffer for drive strings
);
Parameters

nBufferLength

Specifies the maximum size, in characters, of the buffer pointed to by lpBuffer. This size does not include the terminating null character.

lpBuffer

Points to a buffer that receives a series of null-terminated strings, one for each valid drive in the system, that end with a second null character. The following example shows the buffer contents with <null> representing the terminating null character.

c:\<null>d:\<null><null>

Return Value

If the function succeeds, the return value is the length, in characters, of the strings copied to the buffer, not including the terminating null character. Note that an ANSI-ASCII null character uses one byte, but a Unicode null character uses two bytes.

If the buffer is not large enough, the return value is greater than nBufferLength. It is the size of the buffer required to hold the drive strings.

If the function fails, the return value is zero. To get extended error information, use the GetLastError function.

Remarks

Each string in the buffer may be used wherever a root directory is required, such as for the GetDriveType and GetDiskFreeSpace functions.

See Also

GetDriveType, GetDiskFreeSpace, GetLogicalDrives


GetMailslotInfo

The GetMailslotInfo function retrieves information about the specified mailslot.

BOOL GetMailslotInfo(

HANDLE  hMailslot,	// mailslot handle
LPDWORD  lpMaxMessageSize,	// address of maximum message size
LPDWORD  lpNextSize,	// address of size of next message
LPDWORD  lpMessageCount,	// address of number of messages
LPDWORD  lpReadTimeout	// address of read time-out
);
Parameters

hMailslot

Identifies a mailslot. The CreateMailslot function must create this handle.

lpMaxMessageSize

Points to a buffer specifying the maximum message size, in bytes, allowed for this mailslot, when the function returns. This value can be greater than or equal to the value specified in the cbMaxMsg parameter of the CreateMailslot function that created the mailslot. This parameter can be NULL.

lpNextSize

Points to a buffer specifying the size, in bytes, of the next message, when the function returns. The following value has special meaning:

Value	Meaning
MAILSLOT_NO_MESSAGE	There is no next message.
This parameter can be NULL.

lpMessageCount

Points to a buffer specifying the total number of messages waiting to be read, when the function returns. This parameter can be NULL.

lpReadTimeout

Points to a buffer specifying the amount of time, in milliseconds, a read operation can wait for a message to be written to the mailslot before a time-out occurs. This parameter is filled in when the function returns. This parameter can be NULL.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateMailslot, SetMailslotInfo


GetMapMode

The GetMapMode function retrieves the current mapping mode.

int GetMapMode(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value specifies the mapping mode.

If the function fails, the return value is zero.

Remarks

The following list describes the various mapping modes:

Value	Description
MM_ANISOTROPIC	Logical units are mapped to arbitrary units with arbitrarily scaled axes. Use the SetWindowExtEx and SetViewportExtEx functions to specify the units, orientation, and scaling that you want.
MM_HIENGLISH	Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is up.
MM_HIMETRIC	Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is up.
MM_ISOTROPIC	Logical units are mapped to arbitrary units with equally scaled axes; that is, one unit along the x-axis is equal to one unit along the y-axis. Use the SetWindowExtEx and SetViewportExtEx functions to specify the units and the orientation of the axes that you want. Graphics device interface makes adjustments as necessary to ensure the x and y units remain the same size (for example, if you set the window extent, the viewport will be adjusted to keep the units isotropic).
MM_LOENGLISH	Each logical unit is mapped to 0.01 inch. Positive x is to the right; positive y is up.
MM_LOMETRIC	Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is up.
MM_TEXT	Each logical unit is mapped to one device pixel. Positive x is to the right; positive y is down.
MM_TWIPS	Each logical unit is mapped to one twentieth of a printer's point (1/1440 inch, also called a "twip"). Positive x is to the right; positive y is up.
See Also

SetMapMode, SetWindowExtEx, SetViewportExtEx


GetMenu

The GetMenu function retrieves the handle of the menu assigned to the given window.

HMENU GetMenu(

HWND  hWnd	// handle of window
);
Parameters

hWnd

Identifies the window whose menu handle is retrieved.

Return Value

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

The GetMenuCheckMarkDimensions function returns the dimensions of the default check mark bitmap. Windows displays this bitmap next to checked menu items. Before calling the SetMenuItemBitmaps function to replace the default check mark bitmap for a menu item, an application must determine the correct bitmap size by calling GetMenuCheckMarkDimensions.

LONG GetMenuCheckMarkDimensions(VOID)

Parameters

This function has no parameters.

Return Value

The return value specifies the height and width, in pixels, of the default check mark bitmap. The high-order word contains the height; the low-order word contains the width.

See Also

SetMenuItemBitmaps


GetMenuContextHelpId  (preliminaryWindows NT)
GetMenuContextHelpId  (preliminary−Windows NT)

The GetMenuContextHelpId function retrieves the help context identifier associated with the specified menu.

DWORD GetMenuContextHelpId(

HMENU  hmenu
);
Parameters

hmenu

Handle to the menu for which the help context identifier is to be retrieved.

Return Value

Returns the help context identifier if the menu has one or zero otherwise.


GetMenuDefaultItem  (preliminaryWindows 95)
GetMenuDefaultItem  (preliminary−Windows 95)

The GetMenuDefaultItem function determines the default menu item on the specified menu.

UINT WINAPI GetMenuDefaultItem(

HMENU  hMenu,
UINT  fByPos,
UINT  gmdiFlags
);
Parameters

hMenu

Handle to the menu for which to retrieve the default menu item.

fByPos

Value specifying whether to retrieve the menu item's identifier or its position. If this parameter is FALSE, the identifier is returned. Otherwise, the position is returned.

gmdiFlags

Value specifying how the function searches for menu items. This parameter can be zero or more of the following values:

Value	Meaning
GMDI_GOINTOPOPUPS	Specifies that if the default item is a pop-up item, the function is to search recursively in the corresponding pop-up menu. If the pop-up menu has no default item, the return value identifies the pop-up item. By default, the function returns the first default item on the specified menu, regardless of whether it is a pop-up item.
GMDI_USEDISABLED	Specifies that the function is to return a default item, even if it is disabled.  By default, the function skips disabled or grayed items.
Return Value

If the function succeeds, the return value is the identifier or position of the menu item.

If the function fails, the return value is − 1.


GetMenuItemCount

The GetMenuItemCount function determines the number of items in the specified menu bar or pop-up menu.

int GetMenuItemCount(

HMENU  hMenu	// handle of menu
);
Parameters

hMenu

Identifies the handle of the menu to be examined.

Return Value

If the function succeeds, the return value specifies the number of items in the menu.

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

See Also

GetMenuItemID


GetMenuItemID

The GetMenuItemID function retrieves the menu item identifier of a menu item located at the specified position in a menu bar or pop-up menu.

UINT GetMenuItemID(

HMENU  hMenu,	// handle of menu
int  nPos	// position of menu item
);
Parameters

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.

Return Value

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


GetMenuItemInfo  (preliminaryWindows 95)
GetMenuItemInfo  (preliminary−Windows 95)

The GetMenuItemInfo function retrieves information about a menu item.

BOOL WINAPI GetMenuItemInfo(

HMENU  hMenu,
UINT  uItem,
BOOL  fByPosition,
LPMENUITEMINFO  lpmii
);
Parameters

hMenu

Handle to the menu that contains the menu item.

uItem

Identifier or position of the menu item to get information about. The meaning of this parameter depends on the value of fByPosition.

fByPosition

Value specifying the meaning of uItem. If this parameter is FALSE, uItem is a menu item identifier. Otherwise, it is a menu item position.

lpmii

Pointer to a MENUITEMINFO structure that specifies the information to retrieve and receives information about the menu item.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

See Also

MENUITEMINFO


GetMenuItemRect  (preliminaryWindows 95)
GetMenuItemRect  (preliminary−Windows 95)

The GetMenuItemRect function retrieves the bounding rectangle for the specified menu item.

BOOL WINAPI GetMenuItemRect(

HWND  hWnd,
HMENU  hMenu,
UINT  uItem,
LPRECT  lprcItem
);
Parameters

hWnd

Handle to the window containing the menu bar or pop-up menu.

hMenu

Handle to a menu bar or pop-up menu.

uItem

Zero-based position of the menu item.

lprcItem

Pointer to a RECT structure that receives the bounding rectangle of the specified menu item expressed in screen coordinates.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

See Also

RECT


GetMenuState

The GetMenuState function retrieves the menu flags associated with the specified menu item. If the menu item activates a pop-up menu, this function also returns the number of items in the pop-up menu.

UINT GetMenuState(

HMENU hMenu,	// handle of menu
UINT uId,	// menu item to query
UINT uFlags	// menu flags
);
Parameters

hMenu

Identifies the menu that contains the menu item whose flags are to be retrieved.

uId

Specifies the menu item for which the menu flags are to be retrieved, as determined by the uFlags parameter.

uFlags

Specifies how the uId parameter is interpreted. This parameter can be one of the following values:

Value	Description
MF_BYCOMMAND	Indicates that the uId parameter gives the identifier of the menu item. The MF_BYCOMMAND flag is the default if neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified.
MF_BYPOSITION	Indicates that the uId parameter gives the zero-based relative position of the menu item.
Return Value

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, 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	Description
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

The GetMenuString function copies the text string of the specified menu item into the specified buffer.

int GetMenuString(

HMENU  hMenu,	// handle of menu
UINT  uIDItem,	// menu item identifier
LPTSTR  lpString,	// address of buffer for string
int  nMaxCount,	// maximum length of string
UINT  uFlag	// menu flags
);
Parameters

hMenu

Identifies the menu.

uIDItem

Specifies the menu item to be changed, as determined by the uFlag parameter.

lpString

Points to the buffer that is to receive the null-terminated string.

nMaxCount

Specifies the maximum length, in characters, of the string to be copied. If the string is longer than the maximum specified in the nMaxCount parameter, the extra characters are truncated.

uFlag

Specifies how the uIDItem parameter is interpreted. This parameter must be one of the following values:

Value	Meaning
MF_BYCOMMAND	Indicates that uIDItem gives the identifier of the menu item. If neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified, the MF_BYCOMMAND flag is the default flag.
MF_BYPOSITION	Indicates that uIDItem gives the zero-based relative position of the menu item.
Return Value

If the function succeeds, the return value specifies the number of characters copied to the buffer, not including the terminating null character.

If the function fails, the return value is zero.

Remarks

The nMaxCount parameter must be one larger than the number of characters in the text string to accommodate the terminating null character.

See Also

GetMenuItemID


GetMessage

The GetMessage function retrieves a message from the calling thread's message queue and places it in the specified structure. This function can retrieve both messages associated with a specified window and thread messages posted via the PostThreadMessage function. The function retrieves messages that lie within a specified range of message values. GetMessage does not retrieve messages for windows that belong to other threads or applications.

BOOL GetMessage(

LPMSG  lpMsg,	// address of structure with message
HWND  hWnd,	// handle of window
UINT  wMsgFilterMin,	// first message
UINT  wMsgFilterMax	// last message
);
Parameters

lpMsg

Points to an MSG structure that receives message information from the thread's message queue.

hWnd

Identifies the window whose messages are to be retrieved. One value has a special meaning:

Value	Meaning
NULL	GetMessage retrieves messages for any window that belongs to the calling thread and thread messages posted to the calling thread via PostThreadMessage.
wMsgFilterMin

Specifies the integer value of the lowest message value to be retrieved.

wMsgFilterMax

Specifies the integer value of the highest message value to be retrieved.

Return Value

If the function retrieves a message other than WM_QUIT, the return value is TRUE.

If the function retrieves the WM_QUIT, the return value is FALSE.

If there is an error, the return value is -1. For example, the function fails if hWnd is an invalid window handle.

Remarks

An application typically uses the return value to determine whether to end the main message loop and exit the program.

The GetMessage function only retrieves messages associated with the window identified by the hWnd parameter or any of its children as specified by the IsChild function, and within the range of message values given by the wMsgFilterMin and wMsgFilterMax parameters. If hWnd is NULL, GetMessage retrieves messages for any window that belongs to the calling thread and thread messages posted to the calling thread via PostThreadMessage. GetMessage does not retrieve messages for windows that belong to other threads nor for threads other than the calling thread. Thread messages, posted by the PostThreadmessage function, have a message hWnd value of NULL. If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no range filtering is performed).

The WM_KEYFIRST and WM_KEYLAST constants can be used as filter values to retrieve all messages related to keyboard input; the WM_MOUSEFIRST and WM_MOUSELAST constants can be used to retrieve all mouse messages. If the wMsgFilterMin and wMsgFilterMax parameters are both zero, the GetMessage function returns all available messages (that is, without performing any filtering).

GetMessage does not remove WM_PAINT messages from the queue. The messages remain in the queue until processed.

Note that the function return value can be TRUE, FALSE, or -1. Thus, you should avoid code like this:

while (GetMessage( lpMsg, hWnd, 0, 0)) ...

The possibility of a -1 return value means that such code can lead to fatal application errors.

See Also

IsChild, MSG, PeekMessage, PostMessage, PostThreadMessage, WaitMessage


GetMessageExtraInfo

The GetMessageExtraInfo function retrieves extra information associated with the last message retrieved by the GetMessage or PeekMessage function. This information may be added to a message by the driver for a pointing device or keyboard.

LONG GetMessageExtraInfo(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value specifies the extra information. The meaning of the extra information is device specific.

See Also

GetMessage, PeekMessage


GetMessagePos

The GetMessagePos function returns a long value that gives the cursor position in screen coordinates. This position is the point occupied by the cursor when the last message retrieved by the GetMessage function occurred.

DWORD GetMessagePos(VOID)

Parameters

This function has no parameters.

Return Value

The return value specifies the x- and y-coordinates of the cursor position.

Remarks

The x-coordinate is in the low-order word of the return value; the y-coordinate is in the high-order word. If the return value is assigned to a variable, you can use the MAKEPOINTS macro to obtain a POINTS structure from the return value. You can also use the LOWORD or HIWORD macro to extract the x- or y-coordinate.

To determine the current position of the cursor instead of the position when the last message occurred, use the GetCursorPos function.

See Also

GetCursorPos, GetMessage, GetMessageTime, HIWORD, LOWORD, MAKEPOINTS, POINTS


GetMessageTime

The GetMessageTime function returns the message time for the last message retrieved by the GetMessage function from the current thread's message queue. The time is a long integer that specifies the elapsed time, in milliseconds, from the time the system was started to the time the message was created (that is, placed in the thread's message queue).

LONG GetMessageTime(VOID)

Parameters

This function has no parameters.

Return Value

The return value specifies the message time.

Remarks

The return value from the GetMessageTime function does not necessarily increase between subsequent messages, because the value wraps to zero if the timer count exceeds the maximum value for a long integer.

To calculate time delays between messages, verify that the time of the second message is greater than the time of the first message; then, subtract the time of the first message from the time of the second message.

See Also

GetMessage, GetMessagePos


GetMetaFile

The GetMetaFile function creates a handle that identifies the given Windows-format metafile.

The GetMetaFile function is not implemented in the Win32 API. This function is provided for compatibility with 16-bit versions of Microsoft Windows. Win32-based applications should use the GetEnhMetaFile function.

HMETAFILE GetMetaFile(

LPCTSTR  lpszFile	// address of metafile name
);
Parameters

lpszFile

Points to the null-terminated string that specifies the name of a Windows-format metafile. (The metafile must already exist.)

Return Value

If the function succeeds, the return value is a handle of the Windows-format metafile.

If the function fails, the return value is NULL.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced-format metafile functions.

An application can 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, GetEnhMetaFile, SetWinMetaFileBits


GetMetaFileBits

The GetMetaFile function is not implemented in the Win32 API. This function is provided for compatibility with 16-bit versions of Microsoft Windows. Win32-based applications should use the GetMetaFileBitsEx function.


GetMetaFileBitsEx

The GetMetaFileBitsEx function retrieves the contents of a Windows-format metafile and copies them into the specified buffer.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the GetEnhMetaFileBits function.

UINT GetMetaFileBitsEx(

HMETAFILE  hmf,	// handle of metafile
UINT  nSize,	// size of metafile, in bytes
LPVOID  lpvData	// address of metafile data
);
Parameters

hmf

Identifies a Windows-format metafile.

nSize

Specifies the size, in bytes, of the buffer to receive the data.

lpvData

Points to the buffer to receive the metafile data. The buffer must be sufficiently large to contain the data. If lpvData is NULL, the function returns the number of bytes required to hold the data.

Return Value

If the function succeeds and the buffer pointer is NULL, the return value is the number of bytes required for the buffer; if the function succeeds and the buffer pointer is a valid pointer, the return value is the number of bytes copied.

If the function fails, the return value is zero.

Remarks

After the Windows-metafile bits are retrieved, they can be used to create a memory-based metafile by calling the SetMetaFileBitsEx function.

The GetMetaFileBitsEx function does not invalidate the metafile handle. An application must delete this handle by calling the DeleteMetaFile function.

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced format metafile functions.

To convert a Windows-format metafile into an enhanced-format metafile, use the SetWinMetaFileBits function.

See Also

BeginPath, DeleteMetaFile, GetEnhMetaFileBits, PolyBezier, SetMetaFileBitsEx, SetWinMetaFileBits, SetWorldTransform


GetMetaRgn

The GetMetaRgn function retrieves the current metaregion for the specified device context.

int GetMetaRgn(

HDC  hdc,	// handle of device context
HRGN  hrgn	// handle of region
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies an existing region before the function is called. After the function returns, this parameter identifies a copy of the current metaregion.

Return Value

If the function succeeds, the return value is one.

If the function fails, the return value is zero.

Remarks

If the function succeeds, hrgn identifies a copy of the current metaregion. Subsequent changes to this copy will not affect the current metaregion.

The current clipping region of a device context is defined by the intersection of its clipping region and its metaregion.

See Also

SetMetaRgn


GetMiterLimit

The GetMiterLimit function returns the miter limit for the specified device context.

BOOL GetMiterLimit(

HDC  hdc,	// handle of device context
PFLOAT  peLimit	// address of variable receiving miter limit
);
Parameters

hdc

Identifies the device context.

peLimit

Points to a floating-point value where the current miter limit will be returned.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The miter limit is used when drawing geometric lines that have miter joins.

See Also

ExtCreatePen, SetMiterLimit


GetModuleFileName

The GetModuleFileName function retrieves the full path and filename for the executable file containing the specified module.

Windows 95 only: The GetModuleFilename function will return long filenames when an application's version number is greater than or equal to 4.00.

DWORD GetModuleFileName(

HMODULE  hModule,	// handle of module to find filename for
LPTSTR  lpFilename,	// address of buffer for module path
DWORD  nSize	// size of buffer, in characters
);
Parameters

hModule

Identifies the module whose executable filename is being requested. If this parameter is NULL, GetModuleFileName returns the path for the file used to create the calling process.

lpFilename

Points to a buffer that is filled in with the path and filename of the given module.

nSize

Specifies the length, in characters, of the lpFilename buffer. If the length of the path and filename exceeds this limit, the string is truncated.

Return Value

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If a module is loaded in two processes, its module filename in one process may differ in case from its module filename in the other process.

See Also

GetModuleHandle, LoadLibrary


GetModuleHandle

The GetModuleHandle function returns a module handle for the specified module if the file has been mapped into the address space of the calling process.

HMODULE GetModuleHandle(

LPCTSTR  lpModuleName	// address of module name to return handle for
);
Parameters

lpModuleName

Points to a null-terminated string that names a Win32 module (either a .DLL or .EXE file). If the filename extension is omitted, the default library extension .DLL is appended. The filename string can include a trailing point character (.) to indicate that the module name has no extension. The string does not have to specify a path. The name is compared (case independently) to the names of modules currently mapped into the address space of the calling process.

If this parameter is NULL, GetModuleHandle returns a handle of the file used to create the calling process.

Return Value

If the function succeeds, the return value is a handle to the specified module.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The returned handle is not global, inheritable, or duplicative, and it cannot be used by another process.

The handles returned by GetModuleHandle and LoadLibrary can be used in the same functions — for example, GetProcAddress, FreeLibrary, or LoadResource. The difference between the two functions involves the reference count. LoadLibrary maps the module into the address space of the calling process, if necessary, and increments the module's reference count, if it is already mapped. GetModuleHandle, however, returns the handle of a mapped module without incrementing its reference count.

Note that the reference count is used in FreeLibrary to determine whether to unmap the function from the address space of the process. For this reason, use care when using a handle returned by GetModuleHandle in a call to FreeLibrary because doing so can cause a dynamic-link library (DLL) module to be unmapped prematurely.

This function must also be used carefully in a multithreaded application. There is no guarantee that the module handle remains valid between the time this function returns the handle and the time it is used by another function. For example, a thread might retrieve a module handle by calling GetModuleHandle. Before the thread uses the handle in another function, a second thread could free the module and the system could load another module, giving it the same handle as the module that was recently freed. The first thread would then be left with a module handle that refers to a module different than the one intended.

See Also

FreeLibrary, GetModuleFileName, GetProcAddress, LoadLibrary, LoadResource


GetModuleUsage

The GetModuleUsage function has been deleted. Each Win32-based application runs in its own address space.


GetMsgProc

The GetMsgProc hook procedure is an application-defined or library-defined callback function that the system calls whenever the GetMessage function has retrieved a message from an application message queue. Before passing the retrieved message to the destination window procedure, the system passes the message to the hook procedure.

LRESULT CALLBACK GetMsgProc(

int  code,	// hook code
WPARAM  wParam,	// removal flag
LPARAM  lParam	// address of structure with message
);
Parameters

code

Specifies whether the hook procedure must process the message. If code is HC_ACTION, the hook procedure must process the message. If code is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies whether the message has been removed from the queue. This parameter can be one of the following values:

Value	Meaning
PM_NOREMOVE	Specifies that the message has not been removed from the queue. (An application called the PeekMessage function, specifying the PM_NOREMOVE flag.)
PM_REMOVE	Specifies that the message has been removed from the queue. (An application called GetMessage, or it called the PeekMessage function, specifying the PM_REMOVE flag.)
lParam

Points to an MSG structure that contains details about the message.

Return Value

The return value should be zero.

Remarks

The GetMsgProc hook procedure can examine or modify the message. After the hook procedure returns control to the system, the GetMessage function returns the message, along with any modifications, to the application that originally called it.

An application installs this hook procedure by specifying the WH_GETMESSAGE hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

GetMsgProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, GetMessage, MSG, PeekMessage, SetWindowsHookEx


GetNameByType

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

INT GetNameByType(lpServiceType, lpServiceName, dwNameLength

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

lpServiceType

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

lpServiceName

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

dwNameLength

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

Return Value

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

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

See Also

GetTypeByName


GetNamedPipeHandleState

The GetNamedPipeHandleState function retrieves information about a specified named pipe. The information returned can vary during the lifetime of an instance of the named pipe.

BOOL GetNamedPipeHandleState(

HANDLE  hNamedPipe,	// handle of named pipe
LPDWORD  lpState,	// address of flags indicating pipe state
LPDWORD  lpCurInstances,	// address of number of current pipe instances
LPDWORD  lpMaxCollectionCount,	// address of max. bytes before remote transmission
LPDWORD  lpCollectDataTimeout,	// address of max. time before remote transmission
LPTSTR  lpUserName,	// address of user name of client process
DWORD  nMaxUserNameSize	// size, in characters, of user name buffer
);
Parameters

hNamedPipe

Identifies the named pipe for which information is wanted. The handle must have GENERIC_READ access to the named pipe.

lpState

Points to a 32-bit variable that indicates the current state of the handle. This parameter can be NULL if this information is not needed. Either or both of the following values can be specified:

Value	Meaning
PIPE_NOWAIT	The pipe handle is in nonblocking mode. If this flag is not specified, the pipe handle is in blocking mode.
PIPE_READMODE_MESSAGE	The pipe handle is in message-read mode. If this flag is not specified, the pipe handle is in byte-read mode.
lpCurInstances

Points to a 32-bit variable that receives the number of current pipe instances. This parameter can be NULL if this information is not required.

lpMaxCollectionCount

Points to a 32-bit variable that receives the maximum number of bytes to be collected on the client's computer before transmission to the server. This parameter must be NULL if the specified pipe handle is to the server end of a named pipe or if client and server processes are on the same computer. This parameter can be NULL if this information is not required.

lpCollectDataTimeout

Points to a 32-bit variable that receives the maximum time, in milliseconds, that can pass before a remote named pipe transfers information over the network. This parameter must be NULL if the specified pipe handle is to the server end of a named pipe or if client and server processes are on the same computer. This parameter can be NULL if this information is not required.

lpUserName

Points to a buffer that receives the null-terminated string containing the user name string of the client application. This parameter must be NULL if the specified pipe handle is to the client end of a named pipe. This parameter can be NULL if this information is not required.

nMaxUserNameSize

Specifies the size, in characters, of the buffer specified by the lpUserName parameter. This parameter is ignored if lpUserName is NULL.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The GetNamedPipeHandleState function returns successfully even if all of the pointers passed to it are NULL.

To set the pipe handle state, use the SetNamedPipeHandleState function.

See Also

SetNamedPipeHandleState


GetNamedPipeInfo

The GetNamedPipeInfo function retrieves information about the specified named pipe.

BOOL GetNamedPipeInfo(

HANDLE  hNamedPipe,	// handle of named pipe
LPDWORD  lpFlags,	// address of flags indicating type of pipe
LPDWORD  lpOutBufferSize,	// address of size, in bytes, of pipe's output buffer
LPDWORD  lpInBufferSize,	// address of size, in bytes, of pipe's input buffer
LPDWORD  lpMaxInstances	// address of max. number of pipe instances
);
Parameters

hNamedPipe

Identifies the named pipe instance. The handle must have GENERIC_READ access to the named pipe.

lpFlags

Points to a 32-bit variable that indicates the type of the named pipe and specifies whether the handle is to the server or client end of the pipe. This parameter can be NULL if this information is not required. Either or both of the following values can be specified:

Value	Meaning
PIPE_CLIENT_END	Windows 95 only: The handle refers to the client end of a named pipe instance. This is the default.
PIPE_SERVER_END	Windows 95 only: The handle refers to the server end of a named pipe instance. If this value is not specified, the handle refers to the client end of a named pipe instance.
PIPE_TYPE_MESSAGE	The named pipe is a message-type pipe. If this value is not specified, the pipe is a byte-type pipe.
lpOutBufferSize

Points to a 32-bit variable that receives the size, in bytes, of the buffer for outgoing data. If the buffer size is zero, the buffer is allocated as needed. This parameter can be NULL if this information is not required.

lpInBufferSize

Points to a 32-bit variable that receives the size, in bytes, of the buffer for incoming data. If the buffer size is zero, the buffer is allocated as needed. This parameter can be NULL if this information is not required.

lpMaxInstances

Points to a 32-bit variable that receives the maximum number of pipe instances that can be created. If the variable is set to PIPE_UNLIMITED_INSTANCES, the number of pipe instances that can be created is limited only by the availability of system resources. This parameter can be NULL if this information is not required.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateNamedPipe, GetNamedPipeHandleState


GetNearestColor

The GetNearestColor function returns a color value identifying a color from the system palette that will be displayed when the specified color value is used.

COLORREF GetNearestColor(

HDC  hdc,	// handle of device context
COLORREF  crColor	// color to be matched
);
Parameters

hdc

Identifies the device context.

crColor

Specifies a color value that identifies a requested color.

Return Value

If the function succeeds, the return value identifies a color from the system palette that corresponds to the given color value.

If the function fails, the return value is CLR_INVALID. To get extended error information, call GetLastError.

See Also

GetDeviceCaps, GetNearestPaletteIndex, COLORREF


GetNearestPaletteIndex

The GetNearestPaletteIndex function retrieves the index for the entry in the specified logical palette most closely matching a specified color value.

UINT GetNearestPaletteIndex(

HPALETTE  hpal,	// handle of logical color palette
COLORREF  crColor	// color to be matched
);
Parameters

hpal

Identifies a logical color palette.

crColor

Specifies a color to be matched.

Return Value

If the function succeeds, the return value is the index of an entry in a logical palette.

If the function fails, the return value is CLR_INVALID. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

If the given logical palette contains entries with the PC_EXPLICIT flag set, the return value is undefined.

See Also

GetDeviceCaps, GetNearestColor, GetPaletteEntries, GetSystemPaletteEntries, COLORREF


GetNextDlgGroupItem

The GetNextDlgGroupItem function retrieves the handle of the first control in a group of controls that precedes (or follows) the specified control in a dialog box.

HWND GetNextDlgGroupItem(

HWND  hDlg,	// handle of dialog box
HWND  hCtl,	// handle of control
BOOL  bPrevious	// direction flag
);
Parameters

hDlg

Identifies the dialog box being searched.

hCtl

Identifies the control to be used as the starting point for the search. If this parameter is NULL, the function uses the last (or first) control in the dialog box as the starting point for the search.

bPrevious

Specifies how the function is to search the group of controls in the dialog box. If this parameter is TRUE, the function searches for the previous control in the group. If it is FALSE, the function searches for the next control in the group.

Return Value

If GetNextDlgGroupItem succeeds, the return value is the handle of the previous (or next) control in the group of controls.

Remarks

The GetNextDlgGroupItem function searches controls in the order (or reverse order) they were created in the dialog box template. The first control in the group must have the WS_GROUP style; all other controls in the group must have been consecutively created and must not have the WS_GROUP style.

When searching for the previous control, the function returns the first control it locates that is visible and not disabled. If the control given by hCtl has the WS_GROUP style, the function temporarily reverses the search to locate the first control having the WS_GROUP style, then resumes the search in the original direction, returning the first control it locates that is visible and not disabled, or returning hwndCtrl if no such control is found.

When searching for the next control, the function returns the first control it locates that is visible, not disabled, and does not have the WS_GROUP style. If it encounters a control having the WS_GROUP style, the function reverses the search, locates the first control having the WS_GROUP style, and returns this control if it is visible and not disabled. Otherwise, the function resumes the search in the original direction and returns the first control it locates that is visible and not disabled, or returns hCtl if no such control is found.

See Also

GetNextDlgTabItem


GetNextDlgTabItem

The GetNextDlgTabItem function retrieves the handle of the first control that has the WS_TABSTOP style that precedes (or follows) the specified control.

HWND GetNextDlgTabItem(

HWND  hDlg,	// handle of dialog box
HWND  hCtl,	// handle of known control
BOOL  bPrevious	// direction flag
);
Parameters

hDlg

Identifies the dialog box to be searched.

hCtl

Identifies the control to be used as the starting point for the search. If this parameter is NULL, the function uses the last (or first) control in the dialog box as the starting point for the search.

bPrevious

Specifies how the function is to search the dialog box. If this parameter is TRUE, the function searches for the previous control in the dialog box. If this parameter is FALSE, the function searches for the next control in the dialog box.

Return Value

If the function succeeds, the return value is the window handle of the previous (or next) control that has the WS_TABSTOP style set.

Remarks

The GetNextDlgTabItem function searches controls in the order (or reverse order) they were created in the dialog box template. The function returns the first control it locates that is visible, not disabled, and has the WS_TABSTOP style. If no such control exists, the function returns hCtl.

See Also

GetDlgItem, GetNextDlgGroupItem


GetNextWindow

The GetNextWindow function retrieves the handle of the next or previous window in the Z order. The next window is below the specified window; the previous window is above. Windows maintains separate Z orders for topmost windows, top-level windows, and child windows. If the specified window is a topmost window, the function retrieves the handle of the next (or previous) topmost window. If the specified window is a top-level window, the function retrieves the handle of the next (or previous) top-level window. If the specified window is a a child window, the function searches for a handle of the next (or previous) child window.

HWND GetNextWindow(

HWND  hWnd,	// handle of current window
UINT  wCmd	// direction flag
);
Parameters

hWnd

Identifies a window. The window handle retrieved is relative to this window, based on the value of the wCmd parameter.

wCmd

Specifies whether the function returns the handle of the next window or of the previous window. This parameter can be either of the following values:

Value	Meaning
GW_HWNDNEXT	Returns the handle of the window below the given window.
GW_HWNDPREV	Returns the handle of the window above the given window.
Return Value

If the function succeeds, the return value is the handle of the next (or previous) window. If there is no next (or previous) window, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Using this function is the same as calling the GetWindow function with the GW_HWNDNEXT or GW_HWNDPREV flag set.

See Also

GetTopWindow


GetNumberFormat

The GetNumberFormat function formats a number string as a number string customized for a specified locale.

int GetNumberFormat(

LCID  Locale,	// locale for which number string is to be formatted
DWORD  dwFlags,	// bit flag that controls the function's operation
LPCTSTR  lpValue,	// pointer to input number string
CONST NUMBERFMT *  lpFormat,	// pointer to a formatting information structure
LPTSTR  lpNumberStr,	// pointer to output buffer
int  cchNumber	// size of output buffer
);
Parameters

Locale

Specifies the locale for which the number string is to be formatted. If lpFormat is NULL, the function formats the string according to the number format for this locale. If lpFormat is not NULL, the function uses the locale only for formatting information not specified in the NUMBERFMT structure (for example, the locale's string value for the negative sign).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

Contains a bit flag that controls the operation of the function. If lpFormat is non-NULL, this parameter must be zero.

If lpFormat is NULL, you can specify the LOCALE_NOUSEROVERRIDE flag to format the string using the system default number format for the specified locale; or you can specify zero to format the string using any user overrides to the locale's default number format

lpValue

Points to a null-terminated string containing the number string to format.

This string can only contain the following characters:

•	Characters '0' through '9'

•	One decimal point (dot) if the number is a floating-point value

•	A minus sign in the first character position if the number is a negative value

All other characters are invalid. The function returns an error if the string pointed to by lpValue deviates from these rules.

lpFormat

Pointer to a NUMBERFMT structure that contains number formatting information. All members in the structure pointed to by lpFormat must contain appropriate values.

If lpFormat is NULL, the function uses the number format of the specified locale.

lpNumberStr

Points to a buffer to receive the formatted number string.

cchNumber

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpNumberStr buffer. If cchNumber is zero, the function returns the number of bytes or characters required to hold the formatted number string, and the buffer pointed to by lpNumberStr is not used.

Return Value

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the buffer pointed to by lpNumberStr, or if the cchNumber parameter is zero, the number of bytes or characters required to hold the formatted number string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID FLAGS
ERROR_INVALID_PARAMETER

See Also

GetCurrencyFormat, NUMBERFMT


GetNumberOfConsoleInputEvents

The GetNumberOfConsoleInputEvents function retrieves the number of unread input records in the console's input buffer.

BOOL GetNumberOfConsoleInputEvents(

HANDLE  hConsoleInput,	// handle of console input buffer
LPDWORD  lpcNumberOfEvents	// address for number of events
);
Parameters

hConsoleInput

Identifies the console input buffer. The handle must have GENERIC_READ access.

lpcNumberOfEvents

Points to a 32-bit variable that receives the number of unread input records in the console's input buffer.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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

The GetNumberOfConsoleMouseButtons function retrieves the number of buttons on the mouse used by the current console.

BOOL GetNumberOfConsoleMouseButtons(

LPDWORD  lpNumberOfMouseButtons	// address of number of buttons
);
Parameters

lpNumberOfMouseButtons

Points to a 32-bit variable that receives the number of mouse buttons.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

When a console receives mouse input, an INPUT_RECORD structure containing a MOUSE_EVENT_RECORD structure is placed in the console's input buffer. The dwButtonState member of MOUSE_EVENT_RECORD has a bit indicating the state of each mouse button. The bit is 1 if the button is down and 0 if the button is up. To determine the number of bits that are significant, use GetNumberOfConsoleMouseButtons.

See Also

ReadConsoleInput, INPUT_RECORD, MOUSE_EVENT_RECORD


GetNumberOfEventLogRecords

The GetNumberOfEventLogRecords function retrieves the number of records in the specified event log.

BOOL GetNumberOfEventLogRecords(

HANDLE  hEventLog,	// handle to event log
PDWORD  NumberOfRecords	// buffer for number of records
);
Parameters

hEventLog

Identifies the open event log. This handle is returned by the OpenEventLog or OpenBackupEventLog function.

NumberOfRecords

Points to a variable that receives the number of records in the given event log.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetOldestEventLogRecord, OpenBackupEventLog, OpenEventLog


GetObject

The GetObject function obtains information about a specified graphics object. Depending on the graphics object, the function places a filled-in BITMAP, DIBSECTION, EXTLOGPEN, LOGBRUSH, LOGFONT, or LOGPEN structure, or a count of table entries (for a logical palette), into a specified buffer.

int GetObject(

HGDIOBJ  hgdiobj,	// handle to graphics object of interest
int  cbBuffer,	// size of buffer for object information
LPVOID  lpvObject	// pointer to buffer for object information
);
Parameters

hgdiobj

A handle to the graphics object of interest. This can be a handle to one of the following: a logical bitmap, a brush, a font, a palette, a pen, or a device independent bitmap created by calling the CreateDIBSection function.

cbBuffer

Specifies the number of bytes of information to be written to the buffer.

lpvObject

Points to a buffer that is to receive the information about the specified graphics object.

The following table shows the type of information the buffer receives for each type of graphics object you can specify with hgdiobj:

hgdiobj Type	Data Written to *lpvObject
HBITMAP	BITMAP
HBITMAP returned from a call to CreateDIBSection	DIBSECTION, if cbBuffer is set to sizeof(DIBSECTION), or BITMAP, if cbBuffer is set to sizeof(BITMAP)
HPALETTE	a WORD count of the number of entries in the logical palette
HPEN returned from a call to ExtCreatePen	EXTLOGPEN
HPEN	LOGPEN
HBRUSH	LOGBRUSH
HFONT	LOGFONT
If the lpvObject parameter is NULL, the function return value is the number of bytes required to store the information it writes to the buffer for the specified graphics object.

Return Value

If the function succeeds, and lpvObject is a valid pointer, the return value is the number of bytes stored into the buffer.

If the function succeeds, and lpvObject is NULL, the return value is the number of bytes required to hold the information the function would store into the buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The buffer pointed to by the lpvObject parameter must be sufficiently large to receive the information about the graphics object.

If hgdiobj identifies a bitmap created by calling CreateDIBSection, and the specified buffer is large enough, the GetObject function returns a DIBSECTION structure. In addition, the bmBits member of the BITMAP structure contained within the DIBSECTION will contain a pointer to the bitmap's bit values.

If hgdiobj identifies a bitmap created by any other means, GetObject returns only the width, height, and color format information of the bitmap. You can obtain the bitmap's bit values by calling the GetDIBits or GetBitmapBits function.

If hgdiobj identifies a logical palette, GetObject retrieves a two-byte integer that specifies the number of entries in the palette. The function does not retrieve the LOGPALETTE structure defining the palette. To retrieve information about palette entries, an application can call the GetPaletteEntries function.

See Also

CreateDIBSection, GetBitmapBits, GetDIBits, GetPaletteEntries, GetRegionData, BITMAP, DIBSECTION, EXTLOGPEN, LOGBRUSH, LOGFONT, LOGPALETTE, LOGPEN


GetObjectType

The GetObjectType identifies the type of the specified object.

DWORD GetObjectType(

HGDIOBJ  h	// handle of graphic object
);
Parameters

h

Identifies the object.

Return Value

If the function succeeds, the return value identifies the object. This value can be one of the following:

Value	Meaning
OBJ_BITMAP	Bitmap
OBJ_BRUSH	Brush
OBJ_FONT	Font
OBJ_PAL	Palette
OBJ_PEN	Pen
OBJ_EXTPEN	Extended pen
OBJ_REGION	Region
OBJ_DC	Device context
OBJ_MEMDC	Memory device context
OBJ_METAFILE	Metafile
OBJ_METADC	Metafile device context
OBJ_ENHMETAFILE	Enhanced metafile
OBJ_ENHMETADC	Enhanced metafile device context
If the function fails, the return value is zero.

See Also

GetObject, SelectObject


GetOEMCP

The GetOEMCP function retrieves the current OEM code-page identifier for the system. (OEM stands for original equipment manufacturer.)

UINT GetOEMCP(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the current OEM code-page identifier for the system or a default identifier if no code page is current.

Remarks

Following are the OEM code-page identifiers:

Identifier	Meaning
437	MS-DOS United States
708	Arabic (ASMO 708)
709	Arabic (ASMO 449+, BCON V4)
710	Arabic (Transparent Arabic)
720	Arabic (Transparent ASMO)
737	Greek (formerly 437G)
775	Baltic
850	MS-DOS Multilingual (Latin I)
852	MS-DOS Slavic (Latin II)
855	IBM Cyrillic (primarily Russian)
857	IBM Turkish
860	MS-DOS Portuguese
861	MS-DOS Icelandic
862	Hebrew
863	MS-DOS Canadian-French
864	Arabic
865	MS-DOS Nordic
866	MS-DOS Russian (former USSR)
869	IBM Modern Greek
874	Thai
932	Japan
936	Chinese (PRC, Singapore)
949	Korean
950	Chinese (Taiwan, Hong Kong)
1361	Korean (Johab)
See Also

GetACP


GetOldestEventLogRecord

The GetOldestEventLogRecord function retrieves the absolute record number of the oldest record in the specified event log.

BOOL GetOldestEventLogRecord(

HANDLE  hEventLog,	// handle to event log
PDWORD  OldestRecord	// buffer for number of oldest record
);
Parameters

hEventLog

Identifies the open event log. This handle is returned by the OpenEventLog or OpenBackupEventLog function.

OldestRecord

Points to the variable that receives the absolute record number of the oldest record in the given event log.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetNumberOfEventLogRecords, OpenBackupEventLog, OpenEventLog


GetOpenClipboardWindow

The GetOpenClipboardWindow function retrieves the handle of the window that currently has the clipboard open.

HWND GetOpenClipboardWindow(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the handle of the window that has the clipboard open. If no window has the clipboard open, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If an application or dynamic-link library (DLL) specifies a NULL window handle when calling the OpenClipboard function, the clipboard is opened but is not associated with a window. In such a case, GetOpenClipboardWindow returns NULL.

See Also

GetClipboardOwner, GetClipboardViewer, GetOpenClipboardWindow, OpenClipboard


GetOpenFileName

The GetOpenFileName function creates a system-defined dialog box that enables the user to select a file to open.

BOOL GetOpenFileName(

LPOPENFILENAME  lpofn	// address of structure with initialization data
);
Parameters

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.

Return Value

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.

To get extended error information, call CommDlgExtendedError. CommDlgExtendedError may return one of the following error codes:

CDERR_FINDRESFAILURE	CDERR_NOHINSTANCE
CDERR_INITIALIZATION	CDERR_NOHOOK
CDERR_LOCKRESFAILURE	CDERR_NOTEMPLATE
CDERR_LOADRESFAILURE	CDERR_STRUCTSIZE
CDERR_LOADSTRFAILURE	FNERR_BUFFERTOOSMALL
CDERR_MEMALLOCFAILURE	FNERR_INVALIDFILENAME
CDERR_MEMLOCKFAILURE	FNERR_SUBCLASSFAILURE
Remarks

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, GetOpenFileName must return a handle of the brush that should be used to paint the control background.

Ending the dialog box from within the hook function by calling the EndDialog function prevents the COMDLG32.DLL dynamic link library (DLL) from properly exiting its worker thread. For applications that dynamically load and/or unload COMDLG32.DLL, this type of exiting may result in an access violation during unloading as the worker thread's address space is invalidated.

See Also

CommDlgExtendedError, EndDialog, GetSaveFileName, OPENFILENAME


GetOutlineTextMetrics

The GetOutlineTextMetrics function retrieves text metrics for TrueType fonts.

UINT GetOutlineTextMetrics(

HDC  hdc,	// handle of device context
UINT  cbData,	// size of metric data array
LPOUTLINETEXTMETRIC  lpOTM	// address of metric data array
);
Parameters

hdc

Identifies the device context.

cbData

Specifies the size, in bytes, of the array in which the text metrics are to be returned.

lpOTM

Points to an array of OUTLINETEXTMETRIC structures. If this parameter is NULL, the function returns the size of the buffer required for the retrieved metric data.

Return Value

If the function succeeds, the return value is TRUE or the size of the required buffer.

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

Remarks

The OUTLINETEXTMETRIC structure contains most of the text metric information provided for TrueType fonts (including a TEXTMETRIC structure). The sizes returned in the OUTLINETEXTMETRIC structures are in logical units; they depend on the current mapping mode.

See Also

GetTextMetrics, OUTLINETEXTMETRIC, TEXTMETRIC


GetOverlappedResult

The GetOverlappedResult function returns the results of an overlapped operation on the specified file, named pipe, or communications device.

BOOL GetOverlappedResult(

HANDLE  hFile,	// handle of file, pipe, or communications device
LPOVERLAPPED  lpOverlapped,	// address of overlapped structure
LPDWORD  lpNumberOfBytesTransferred,	// address of actual bytes count
BOOL  bWait	// wait flag
);
Parameters

hFile

Identifies the file, named pipe, or communications device. This is the same handle that was specified when the overlapped operation was started by a call to the ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl, or WaitCommEvent function.

lpOverlapped

Points to an OVERLAPPED structure that was specified when the overlapped operation was started.

lpNumberOfBytesTransferred

Points to a 32-bit variable that receives the number of bytes that were actually transferred by a read or write operation. For a TransactNamedPipe operation, this is the number of bytes that were read from the pipe. For a DeviceIoControl operation, this is the number of bytes of output data returned by the device driver. For a ConnectNamedPipe or WaitCommEvent operation, this value is undefined.

bWait

Specifies whether the function should wait for the pending overlapped operation to be completed. If TRUE, the function does not return until the operation has been completed. If FALSE and the operation is still pending, the function returns FALSE and the GetLastError function returns ERROR_IO_INCOMPLETE.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The results reported by the GetOverlappedResult function are those of the specified handle's last overlapped operation to which the specified OVERLAPPED structure was provided, and for which the operation's results were pending. A pending operation is indicated when the function that started the operation returns FALSE, and the GetLastError function returns ERROR_IO_PENDING. When an I/O operation is pending, the function that started the operation resets the hEvent member of the OVERLAPPED structure to the nonsignaled state. Then when the pending operation has been completed, the system sets the event object to the signaled state.

If the bWait parameter is TRUE, GetOverlappedResult determines whether the pending operation has been completed by waiting for the event object to be in the signaled state.

If the hEvent member of the OVERLAPPED structure is NULL, the system uses the state of the hFile handle to signal when the operation has been completed. Use of file, named pipe, or communications-device handles for this purpose is discouraged. It is safer to use an event object because of the confusion that can occur when multiple simultaneous overlapped operations are performed on the same file, named pipe, or communications device. In this situation, there is no way to know which operation caused the object's state to be signaled.

Specify a manual-reset event object in the OVERLAPPED structure. If an auto-reset event object is used, the event handle must not be specified in any other wait operation in the interval between starting the overlapped operation and the call to GetOverlappedResult. For example, the event object is sometimes specified in one of the wait functions to wait for the operation's completion. When the wait function returns, the system sets an auto-reset event's state to nonsignaled, and a subsequent call to GetOverlappedResult with the bWait parameter set to TRUE causes the function to be blocked indefinitely.

See Also

ConnectNamedPipe, CreateEvent, DeviceIoControl, GetLastError, OVERLAPPED, ReadFile, TransactNamedPipe, WaitCommEvent, WriteFile


GetPaletteEntries

The GetPaletteEntries function retrieves a specified range of palette entries from the given logical palette.

UINT GetPaletteEntries(

HPALETTE  hpal,	// handle of logical color palette
UINT  iStartIndex,	// first entry to retrieve
UINT  nEntries,	// number of entries to retrieve
LPPALETTEENTRY  lppe	// address of array receiving entries
);
Parameters

hpal

Identifies the logical color palette.

iStartIndex

Specifies the first entry in the logical palette to be retrieved.

nEntries

Specifies the number of entries in the logical palette to be retrieved.

lppe

Points to an array of PALETTEENTRY structures to receive the palette entries. The array must contain at least as many structures as specified by the nEntries parameter.

Return Value

If the function succeeds and the handle of the logical color palette is a valid pointer (not NULL), the return value is the number of entries retrieved from the logical palette. If the function succeeds and handle of the logical color palette is NULL, the return value is the number of entries in the given palette.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

If the nEntries parameter specifies more entries than exist in the palette, the remaining members of the PALETTEENTRY structure are not altered.

See Also

GetDeviceCaps, GetSystemPaletteEntries, PALETTEENTRY


GetParent

The GetParent function retrieves the handle of the specified child window's parent window.

HWND GetParent(

HWND  hWnd	// handle of child window
);
Parameters

hWnd

Identifies the window whose parent window handle is to be retrieved.

Return Value

If the function succeeds, the return value is the handle of the parent window. If the window has no parent window, the return value is NULL. To get extended error information, call GetLastError.

See Also

SetParent


GetPath

The GetPath function retrieves the coordinates defining the endpoints of lines and the control points of curves found in the path that is selected into the specified device context.

int GetPath(

HDC  hdc,	// handle of device context
LPPOINT  lpPoints,	// address of array receiving path vertices
LPBYTE  lpTypes,	// address of array of path vertex types
int  nSize	// count of points defining path
);
Parameters

hdc

Identifies a device context that contains a closed path.

lpPoints

Points to an array of POINT structures that contains the line endpoints and curve control points.

lpTypes

Points to an array of bytes where the vertex types are placed. Values are one of the following:

Type	Description
PT_MOVETO	Specifies that the corresponding point in the lpPoints parameter starts a disjoint figure.
PT_LINETO	Specifies that the previous point and the corresponding point in lpPoints are the endpoints of a line.
PT_BEZIERTO	Specifies that the corresponding point in lpPoints is a control point or ending point for a Bézier curve.
	PT_BEZIERTO values always occur in sets of three. The point in the path immediately preceding them defines the starting point for the Bézier curve. The first two PT_BEZIERTO points are the control points, and the third PT_BEZIERTO point is the ending (if hard-coded) point.
A PT_LINETO or PT_BEZIERTO value may be combined with the following value (by using the bitwise operator OR) to indicate that the corresponding point is the last point in a figure and the figure should be closed:

Flag	Description
PT_CLOSEFIGURE	Specifies that the figure is automatically closed after the corresponding line or curve is drawn. The figure is closed by drawing a line from the line or curve endpoint to the point corresponding to the last PT_MOVETO.
nSize

Specifies the total number of POINT structures that may be placed in the array pointed to by lpPoints. This value must be the same as the number of bytes that may be placed in the array pointed to by lpTypes.

Return Value

If the nSize parameter is nonzero, the return value is the number of points enumerated. If nSize is 0, the return value is the total number of points in the path (and GetPath writes nothing to the buffers). If nSize is nonzero and is less than the number of points in the path, the return value is −1. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_BUFFER_OVERFLOW

Remarks

The device context identified by the hdc parameter must contain a closed path.

The points of the path are returned in logical coordinates. Points are stored in the path in device coordinates, so GetPath changes the points from device coordinates to logical coordinates by using the inverse of the current transformation.

The FlattenPath function may be called before GetPath to convert all curves in the path into line segments.

See Also

FlattenPath, POINT, PolyDraw, WidenPath


getpeername

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

int getpeername(

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

s

A descriptor identifying a connected socket.

name

The structure which is to receive the name of the peer.

namelen

A pointer to the size of the name structure.

Return Value

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

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEFAULT	The namelen argument is not large enough.
WSAEINPROGRESS	A blocking Windows Sockets call is in progress.
WSAENOTCONN	The socket is not connected.
WSAENOTSOCK	The descriptor is not a socket.
Remarks

The getpeername function retrieves the name of the peer connected to the socket s and stores it in the socket address structure identified by name. It is used on a connected datagram or stream socket.

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

See Also

bind, getsockname, socket


GetPixel

The GetPixel function retrieves the red, green, blue (RGB) color value of the pixel at the specified coordinates.

COLORREF GetPixel(

HDC  hdc,	// handle of device context
int  nXPos,	// x-coordinate of pixel
int  nYPos	// y-coordinate of pixel
);
Parameters

hdc

Identifies the device context.

nXPos

Specifies the logical x-coordinate of the pixel to be examined.

nYPos

Specifies the logical y-coordinate of the pixel to be examined.

Return Value

If the function succeeds, the return value is an RGB value. If the pixel is outside of the current clipping region, the return value is CLR_INVALID.

Remarks

The pixel must be within the boundaries of the current clipping region.

Not all devices support GetPixel. An application should call GetDeviceCaps to determine whether a specified device supports this function.

See Also

GetDeviceCaps


GetPolyFillMode

The GetPolyFillMode function retrieves the current polygon fill mode.

int GetPolyFillMode(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value specifies the polygon fill mode, which can be either of the following values:

Value	Meaning
ALTERNATE	Selects alternate mode (fills area between odd-numbered and even-numbered polygon sides on each scan line).
WINDING	Selects winding mode (fills any region with a nonzero winding value).
If an error occurs, the return value is zero.

See Also

SetPolyFillMode


GetPrinter

The GetPrinter function retrieves information about a specified printer.

BOOL GetPrinter(

HANDLE  hPrinter,	// handle to printer of interest
DWORD  Level,	// version of printer info data structure
LPBYTE  pPrinter,	// pointer to array of bytes that receives printer info. structure
DWORD  cbBuf,	// size, in bytes, of array of bytes
LPDWORD  pcbNeeded	// pointer to variable with count of bytes retrieved (or required)
);
Parameters

hPrinter

Handle to the printer of interest.

Level

Specifies the level, or type, of PRINTER_INFO_* structure that the function stores into the buffer pointed to by pPrinter.

Windows 95: This value can be 1, 2, or 5.

Windows NT: This value can be 1, 2, 3, or 4.

pPrinter

Pointer to a buffer that receives a PRINTER_INFO_* structure. This structure contains information about the specified printer. The type of structure is determined by the value of Level.

Windows 95: The buffer can receive a PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_5 structure.

Windows NT: The buffer can receive a PRINTER_INFO_1, PRINTER_INFO_2, or PRINTER_INFO_3 or PRINTER_INFO_4, structure.

cbBuf

Specifies the size, in bytes, of the buffer pointed to by pPrinter.

pcbNeeded

Pointer to a variable that the function sets to the size in bytes of the printer information. If cbBuf is smaller than this value, GetPrinter fails, and the value represents the required buffer size. If cbBuf is equal to or greater than this value, GetPrinter succeeds, and the value represents the number of bytes stored into the buffer.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the structure returned in the buffer pointed to by the pPrinter parameter contains a pointer to a security descriptor, only those components of the security descriptor that the caller has permission to read will be present. An application that wants to retrieve particular security descriptor components must open the printer with sufficient access permission. The following table shows the security descriptor components that are retrieved for particular access permission values:

Access Permission	Security Descriptor Components Retrieved
READ_CONTROL	Owner, Primary Group, Discretionary access-control list (ACL)
ACCESS_SYSTEM_SECURITY	System ACL
See Also

AbortPrinter, AddPrinter, ClosePrinter, DeletePrinter, EnumPrinters, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4, PRINTER_INFO_5, OpenPrinter, SetPrinter


GetPrinterData

The GetPrinterData function retrieves printer-configuration data for the specified printer.

DWORD GetPrinterData(

HANDLE  hPrinter,	// handle of printer object
LPTSTR  pValueName,	// address of data type
LPDWORD  pType,	// reserved
LPBYTE  pData,	// address of array of bytes that receives data
DWORD  nSize,	// size, in bytes, of array
LPDWORD  pcbNeeded	// address of variable with number of bytes retrieved (or required)
);
Parameters

hPrinter

Identifies the printer for which configuration data should be retrieved.

pValueName

Points to a null-terminated string that specifies the type of data that the function should retrieve.

pType

Points to a variable that receives the data type stored by the SetPrinterData function. GetPrinterData passes pType on as the lpdwType parameter of a RegQueryValueEx function call. This parameter may be NULL.

pData

Points to an array of bytes that receives the configuration data.

nSize

Specifies the size, in bytes, of the buffer pointed to by pData.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if nSize is too small.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The printer handle identified by the hPrinter parameter is obtained by calling the OpenPrinter function.

GetPrinterData retrieves printer-configuration data set by the SetPrinter function.

See Also

OpenPrinter, RegQueryValueEx, SetPrinter, SetPrinterData,


GetPrinterDriver

The GetPrinterDriver function retrieves driver data for the specified printer.

BOOL GetPrinterDriver(

HANDLE  hPrinter,	// printer object
LPTSTR  pEnvironment,	// address of environment
DWORD  Level,	// structure level
LPBYTE  pDriverInfo,	// address of structure array
DWORD  cbBuf,	// size, in bytes, of array
LPDWORD  pcbNeeded	// address of variable with number of bytes retrieved (or required)
);
Parameters

hPrinter

Identifies the printer for which the driver data should be retrieved.

pEnvironment

Points to a null-terminated string that specifies the environment. For example, "Windows NT x86" specifies Windows NT running on an Intel 80386 or 80486 processor. If this parameter is NULL, the current environment of the calling application and client machine (not of the destination application and print server) is used.

Level

Specifies the version of the structure to which lpbForm points. This value must be either 1, 2., or 3.

Windows 95

The value can be 1, 2, or 3.

Windows NT

The value must be either 1 or 2.

pDriverInfo

Points to either a DRIVER_INFO_1, DRIVER_INFO_2, or DRIVER_INFO_3structure. If Level is 1, this array receives a DRIVER_INFO_1 structure; if Level is 2, this array receives a DRIVER_INFO_2 structure, if Level is 3, this array receives a DRIVER_INFO_3 structure.

Windows 95

All three driver-information structures are supported..

Windows NT

DRIVER_INFO_3 structure is not supported.

cbBuf

Specifies the size, in bytes, of the array at which pDriverInfo points.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds or the number of bytes required if cbBuf is too small.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The printer handle identified by the hPrinter parameter should be retrieved by calling the OpenPrinter function.

The DRIVER_INFO_2 and DRIVER_INFO_3 structures contain a full path and filename specifying the location of the printer driver. An application can use the path and filename to load a printer driver by calling the LoadLibrary function and supplying the path and filename as the single argument.

See Also

AddPrinterDriver, DRIVER_INFO_1, DRIVER_INFO_2, EnumPrinterDrivers, LoadLibrary, OpenPrinter


GetPrinterDriverDirectory

The GetPrinterDriverDirectory function retrieves the path of the printer-driver directory.

BOOL GetPrinterDriverDirectory(

LPTSTR  pName,	// address of server name
LPTSTR  pEnvironment,	// address of environment
DWORD  Level,	// address of structure
LPBYTE  pDriverDirectory,	// address of structure array that receives path
DWORD  cbBuf,	// size, in bytes, of array
LPDWORD  pcbNeeded	// address of variable with number of bytes retrieved (or required)
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server on which the printer driver resides. If this parameter is NULL, the local driver-directory path is retrieved.

pEnvironment

Points to a null-terminated string that specifies the environment. For example, "Windows NT x86" specifies Windows NT running on an Intel 80386 or 80486 processor. If this parameter is NULL, the current environment of the calling application and client machine (not of the destination application and print server) is used.

Level

Specifies the structure level. This value must be 1.

pDriverDirectory

Points to an array of bytes that receives the path.

cbBuf

Specifies the size of the array to which pDriverDirectory points.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds, or the number of bytes required if cbBuf is too small.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AddPrinterDriver


GetPrintProcessorDirectory

The GetPrintProcessorDirectory function retrieves the path for the print processor on the specified server.

BOOL GetPrintProcessorDirectory(

LPTSTR  pName,	// address of server name
LPTSTR  pEnvironment,	// address of environment
DWORD  Level,	// structure level
LPBYTE  pPrintProcessorInfo,	// address of structure array
DWORD  cbBuf,	// size, in bytes, of array
LPDWORD  pcbNeeded	// address of variable with number of bytes retrieved (or required)
);
Parameters

pName

Points to a null-terminated string that specifies the name of the server. If this parameter is NULL, a local path is returned.

pEnvironment

Points to a null-terminated string that specifies the environment. For example, "Windows NT x86" specifies Windows NT running on an Intel 80386 or 80486 processor. If this parameter is NULL, the current environment of the calling application and client machine (not of the destination application and print server) is used.

Level

Specifies the structure level. This value must be 1.

pPrintProcessorInfo

Points to an array of bytes into which the path is copied.

cbBuf

Specifies the size of the buffer pointed to by pPrintProcessorInfo.

pcbNeeded

Points to a value that specifies the number of bytes copied if the function succeeds, or the number of bytes required if cbBuf is too small.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AddPrintProcessor


GetPriorityClass

The GetPriorityClass function returns the priority class for the specified process. This value, together with the priority value of each thread of the process, determines each thread's base priority level.

DWORD GetPriorityClass(

HANDLE  hProcess	// handle to the process
);
Parameters

hProcess

Identifies the process. The handle must have PROCESS_QUERY_INFORMATION access.

Return Value

If the function succeeds, the return value is the priority class of the specified process.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

The process's priority class is one of the following values:

Priority	Meaning
HIGH_PRIORITY_CLASS	Indicates a process that performs time-critical tasks that must be executed immediately for it to run correctly. The threads of a high-priority class process preempt the threads of normal or idle priority class processes. An example is Windows Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all available cycles.
IDLE_PRIORITY_CLASS	Indicates a process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS	Indicates a normal process with no special scheduling needs.
REALTIME_PRIORITY_CLASS	Indicates a process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
Remarks

Every thread has a base priority level determined by the thread's priority value and the priority class of its process. The operating system uses the base priority level of all executable threads to determine which thread gets the next slice of CPU time. Threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level will scheduling of threads at a lower level take place.

For a table that shows the base priority levels for each combination of priority class and thread priority value, see the SetPriorityClass function.

See Also

GetThreadPriority, SetPriorityClass, SetThreadPriority


GetPriorityClipboardFormat

The GetPriorityClipboardFormat function returns the first available clipboard format in the specified list.

int GetPriorityClipboardFormat(

UINT  * paFormatPriorityList,	// address of priority list
int  cFormats	// number of entries in list
);
Parameters

paFormatPriorityList

Points to an array of unsigned integers identifying clipboard formats, in priority order. For a description of the clipboard formats, see the SetClipboardData function.

cFormats

Specifies the number of entries in the paFormatPriorityList array. This value must not be greater than the number of entries in the list.

Return Value

If the function succeeds, the return value is the first clipboard format in the list for which data is available. If the clipboard is empty, the return value is NULL. If the clipboard contains data, but not in any of the specified formats, the return value is −1. To get extended error information, call GetLastError.

See Also

CountClipboardFormats, EnumClipboardFormats, GetClipboardFormatName, IsClipboardFormatAvailable, RegisterClipboardFormat, SetClipboardData


GetPrivateObjectSecurity

The GetPrivateObjectSecurity retrieves information from a protected server object's security descriptor.

BOOL GetPrivateObjectSecurity(

PSECURITY_DESCRIPTOR  ObjectDescriptor,	// address of SD to query
SECURITY_INFORMATION  SecurityInformation,	// requested information
PSECURITY_DESCRIPTOR  ResultantDescriptor,	// address of retrieved SD
DWORD  DescriptorLength,	// size of buffer for retrieved SD
PDWORD  ReturnLength	// address of buffer size required for SD
);
Parameters

ObjectDescriptor

Points to a SECURITY_DESCRIPTOR structure. This is the security descriptor to be queried.

SecurityInformation

Specifies a SECURITY_INFORMATION structure that identifies the security information being requested.

ResultantDescriptor

Points to a buffer receiving a copy of the requested information from the specified security descriptor. The SECURITY_DESCRIPTOR structure is returned in self-relative format.

DescriptorLength

Specifies the size, in bytes, of the buffer pointed to by the ResultantDescriptor parameter.

ReturnLength

Points to a variable the function sets to zero if the descriptor is copied successfully. If the buffer is too small for the security descriptor, this variable receives the number of bytes required. If this variable's value is greater than the value of the DescriptorLength parameter when the function returns, the function returns FALSE and none of the security descriptor is copied to the buffer.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application must perform appropriate access/privilege checks and audits before calling this function.

See Also

CreatePrivateObjectSecurity, DestroyPrivateObjectSecurity, GetFileSecurity, GetKernelObjectSecurity, GetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetPrivateObjectSecurity


GetPrivateProfileInt

The GetPrivateProfileInt function retrieves an integer associated with a key in the specified section of the given initialization file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

UINT GetPrivateProfileInt(

LPCTSTR  lpAppName,	// address of section name
LPCTSTR  lpKeyName,	// address of key name
INT  nDefault,	// return value if key name is not found
LPCTSTR  lpFileName	// address of initialization filename
);
Parameters

lpAppName

Points to a null-terminated string containing the section name in the initialization file.

lpKeyName

Points to the null-terminated string containing the key name whose value is to be retrieved. This value is in the form of a string; the GetPrivateProfileInt function converts the string into an integer and returns the integer.

nDefault

Specifies the default value to return if the key name cannot be found in the initialization file.

lpFileName

Points to a null-terminated string that names the initialization file. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

Return Value

If the function succeeds, the return value is the integer equivalent of the string following the specified key name in the specified initialization file. If the key is not found, the return value is the specified default value. If the value of the key is less than zero, the return value is zero.

Remarks

The function searches the file for a key that matches the name specified by the lpKeyName parameter under the section name specified by the lpAppName parameter. A section in the initialization file must have the following form:

[section]
key=value
      .
      .
      .

The GetPrivateProfileInt function is not case-sensitive; the strings in lpAppName and lpKeyName can be a combination of uppercase and lowercase letters.

An application can use the GetProfileInt function to retrieve an integer value from the WIN.INI file.

Windows NT: Calls to private profile functions may be mapped to the registry instead of to the specified initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

This mapping is likely if an application modifies system-component initialization files, such as CONTROL.INI, SYSTEM.INI, and WINFILE.INI. In these cases, the GetPrivateProfileInt function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

GetProfileInt, WritePrivateProfileString


GetPrivateProfileSection

The GetPrivateProfileSection function retrieves all of the keys and values for the specified section from an initialization file. This function is provided for compatibility with 16-bit applications written for Windows. Win32-based applications should store initialization information in the registry.

Windows 95

The specified profile section must not exceed 32K.

Windows NT

The specified profile section has no size limit.

DWORD GetPrivateProfileSection(

LPCTSTR  lpAppName,	// address of section name
LPTSTR  lpReturnedString,	// address of return buffer
DWORD  nSize,	// size of return buffer
LPCTSTR  lpFileName	// address of initialization filename
);
Parameters

lpAppName

Points to a null-terminated string containing the section name in the initialization file.

lpReturnedString

Points to a buffer that receives the key name and value pairs associated with the named section. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpReturnedString parameter.

Windows 95

The maximum buffer size is 32,767 characters.

Windows NT

There is no maximum buffer size.

lpFileName

Points to a null-terminated string that names the initialization file. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

Return Value

The return value specifies the number of characters copied to the buffer, not including the terminating null character. If the buffer is not large enough to contain all the key name and value pairs associated with the named section, the return value is equal to nSize minus two.

Remarks

The data in the buffer pointed to by the lpReturnedString parameter consists of one or more null-terminated strings, followed by a final null character. Each string has the following format:

key=string

The GetPrivateProfileSection function is not case-sensitive; the string pointed to by the lpAppName parameter can be a combination of uppercase and lowercase letters.

This operation is atomic; no updates to the specified initialization file are allowed while the key name and value pairs for the section are being copied to the buffer pointed to by the lpReturnedString parameter.

Windows NT: Calls to private profile functions may be mapped to the registry instead of to the specified initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

This mapping is likely if an application modifies system-component initialization files, such as CONTROL.INI, SYSTEM.INI, and WINFILE.INI. In these cases, the GetPrivateProfileSection function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

GetProfileSection, WritePrivateProfileSection


GetPrivateProfileSectionNames  (preliminaryWindows NT)
GetPrivateProfileSectionNames  (preliminary−Windows NT)

The GetPrivateProfileSectionNames function retrieves the names of all sections in an initialization file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

DWORD GetPrivateProfileSectionNames(

LPTSTR  lpszReturnBuffer,	// address of return buffer
DWORD  nSize,	// size of return buffer
LPCTSTR  lpFileName	// address of initialization filename
);
Parameters

lpszReturnBuffer

Points to a buffer that receives the section names associated with the named file. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpszReturnBuffer parameter.

lpFileName

Points to a null-terminated string that names the initialization file. If this parameter is NULL, the function searches the WIN.INI file. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

Return Value

The return value specifies the number of characters copied to the specified buffer, not including the terminating null character. If the buffer is not large enough to contain all the section names associated with the specified initialization file, the return value is equal to the length specified by nSize minus two.

Remarks

This operation is atomic; no updates to the initialization file are allowed while the section names are being copied to the buffer.

Calls to profile functions might be mapped to the registry instead of to the initialization files. When the operation has been mapped, the GetPrivateProfileSectionNames function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

GetPrivateProfileSection, WritePrivateProfileSection


GetPrivateProfileString

The GetPrivateProfileString function retrieves a string from the specified section in an initialization file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

DWORD GetPrivateProfileString(

LPCTSTR  lpAppName,	// points to section name
LPCTSTR  lpKeyName,	// points to key name
LPCTSTR  lpDefault,	// points to default string
LPTSTR  lpReturnedString,	// points to destination buffer
DWORD  nSize,	// size of destination buffer
LPCTSTR  lpFileName	// points to initialization filename
);
Parameters

lpAppName

Points to a null-terminated string that specifies the section containing the key name. If this parameter is NULL, the GetPrivateProfileString function copies all section names in the file to the supplied buffer.

lpKeyName

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 lpAppName parameter are copied to the buffer specified by the lpReturnedString parameter.

lpDefault

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.

lpReturnedString

Points to the buffer that receives the retrieved string.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpReturnedString parameter.

lpFileName

Points to a null-terminated string that names the initialization file. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

Return Value

If the function succeeds, the return value is the number of characters copied to the buffer, not including the terminating null character.

If neither lpAppName nor lpKeyName is NULL and the supplied destination buffer is too small to hold the requested string, the string is truncated and followed by a null character, and the return value is equal to nSize minus one.

If either lpAppName or lpKeyName is NULL and the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters. In this case, the return value is equal to nSize minus two.

Remarks

The GetPrivateProfileString function searches the specified initialization file for a key that matches the name specified by the lpKeyName parameter under the section heading specified by the lpAppName parameter. If it finds the key, the function copies the corresponding string to the buffer. If the key does not exist, the function copies the default character string specified by the lpDefault parameter. A section in the initialization file must have the following form:

[section]
key=string
      .
      .
      .

If lpAppName is NULL, GetPrivateProfileString copies all section names in the specified file to the supplied buffer. If lpKeyName is NULL, the function copies all key names in the specified section to the supplied buffer. An application can use this method to enumerate all of the sections and keys in a file. In either case, each string is followed by a null character and the final string is followed by a second null character. If the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters.

If the string associated with lpKeyName is enclosed in single or double quotation marks, the marks are discarded when the GetPrivateProfileString function retrieves the string.

The GetPrivateProfileString function is not case-sensitive; the strings can be a combination of uppercase and lowercase letters.

To retrieve a string from the WIN.INI file, use the GetProfileString function.

Windows NT: Calls to private profile functions may be mapped to the registry instead of to the specified initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

This mapping is likely if an application modifies system-component initialization files, such as CONTROL.INI, SYSTEM.INI, and WINFILE.INI. In these cases, the GetPrivateProfileString function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

GetProfileString, WritePrivateProfileString


GetPrivateProfileStruct  (preliminaryWindows NT)
GetPrivateProfileStruct  (preliminary−Windows NT)

The GetPrivateProfileStruct function retrieves the data associated with the specified key in the given section of an initialization file. As it retrieves the data, the function calculates a checksum and compares it with the checksum calculated by the WritePrivateProfileStruct function when the data was added to the file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

BOOL GetPrivateProfileStruct(

LPCTSTR  lpszSection,	// address of section name
LPCTSTR  lpszKey,	// address of key name
LPVOID  lpStruct,	// address of return buffer
UINT  uSizeStruct,	// size of return buffer
LPCTSTR  szFile	// address of initialization filename
);
Parameters

lpszSection

Points to a null-terminated string containing the section name in the initialization file.

lpszKey

Points to the null-terminated string containing the key name whose data is to be retrieved.

lpStruct

Points to the buffer that receives the data associated with the file, section, and key names.

uSizeStruct

Specifies the size, in bytes, of the buffer pointed to by the lpStruct parameter.

szFile

Points to a null-terminated string that names the initialization file. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

A section in the initialization file must have the following form:

[section]
key=data
      .
      .
      .

Calls to private profile functions might be mapped to the registry instead of to the specified initialization files. This mapping is likely if an application modifies system-component initialization files, such as CONTROL.INI, SYSTEM.INI, and WINFILE.INI. In these cases, the GetPrivateProfileStruct function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

WritePrivateProfileStruct


GetProcAddress

The GetProcAddress function returns the address of the specified exported dynamic-link library (DLL) function.

FARPROC GetProcAddress(

HMODULE  hModule,	// handle to DLL module
LPCSTR  lpProcName	// name of function
);
Parameters

hModule

Identifies the DLL module that contains the function. The LoadLibrary or GetModuleHandle function returns this handle.

lpProcName

Points to a null-terminated string containing the function name, or specifies the function's ordinal value. If this parameter is an ordinal value, it must be in the low-order word; the high-order word must be zero.

Return Value

If the function succeeds, the return value is the address of the DLL's exported function.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The GetProcAddress function is used to retrieve addresses of exported functions in DLLs.

The spelling and case of the function name pointed to by lpProcName must be identical to that in the EXPORTS statement of the source DLL's module-definition (.DEF) file.

The lpProcName parameter can identify the DLL function by specifying an ordinal value associated with the function in the EXPORTS statement. GetProcAddress verifies that the specified ordinal is in the range 1 through the highest ordinal value exported in the .DEF file. The function then uses the ordinal as an index to read the function's address from a function table. If the .DEF file does not number the functions consecutively from 1 to N (where N is the number of exported functions), an error can occur where GetProcAddress returns an invalid, non-NULL address, even though there is no function with the specified ordinal.

In cases where the function may not exist, the function should be specified by name rather than by ordinal value.

See Also

FreeLibrary, GetModuleHandle, LoadLibrary


GetProcessAffinityMask

The GetProcessAffinityMask function obtains a process affinity mask for the specified process and the system affinity mask for the system.

A process affinity mask is a bit vector in which each bit represents the processors that a process is allowed to run on. A system affinity mask is a bit vector in which each bit represents the processors that are configured into a system.

A process affinity mask is a proper subset of a system affinity mask. A process is only allowed to run on the processors configured into a system.

BOOL GetProcessAffinityMask(

HANDLE  hProcess,	// handle to the process of interest
LPDWORD  lpProcessAffinityMask,	// pointer to structure to receive process affinity mask
LPDWORD  lpSystemAffinityMask	// pointer to structure to receive system affinity mask
);
Parameters

hProcess

An open handle to the process whose affinity mask is desired. This handle must have PROCESS_QUERY_INFORMATION access.

lpProcessAffinityMask

Pointer to a DWORD that the function sets to the process affinity mask for the specified process.

lpSystemAffinityMask

Pointer to a DWORD that the function sets to the system affinity mask for the system.

Return Value

If the function succeeds, the return value is TRUE. Under Windows NT, the successful function sets the DWORD variables pointed to by lpProcessAffinityMask and lpSystemAffinityMask to the appropriate affinity masks.

If the function fails, the return value is FALSE, and the values of the DWORD variables pointed to by lpProcessAffinityMask and lpSystemAffinityMask are undefined.

See Also

SetThreadAffinityMask


GetProcessHeap

The GetProcessHeap function obtains a handle to the heap of the calling process. This handle can then be used in calls to the HeapAlloc, HeapReAlloc, HeapFree, and HeapSize functions.

HANDLE GetProcessHeap(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is a handle to the calling process's heap.

If the function fails, the return value is NULL.

Remarks

GetProcessHeap allows Win32-based applications to allocate memory from the process heap without having to first create a heap with the HeapCreate function, as shown in this example:

HeapAlloc(GetProcessHeap(), 0, dwBytes);

Note that the handle obtained by calling the function should not be used in calls to the HeapDestroy function.

Note, also, that the HEAP_NO_SERIALIZE flag should not be specified when using the HeapAlloc, HeapFree, HeapReAlloc, and HeapSize functions to access the process heap. The system may create additional threads within the application's process, such as a Ctrl+C handler, that simultaneously access the process heap. For more information about HEAP_NO_SERIALIZE, see the HeapCreate function.

See Also

GetProcessHeaps, HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, HeapSize


GetProcessHeaps

The GetProcessHeaps function obtains handles to all of the heaps that are valid for the calling process.

DWORD GetProcessHeaps(

DWORD  NumberOfHeaps,	// maximum number of heap handles buffer can receive
PHANDLE  ProcessHeaps	// points to buffer to receive array of heap handles
);
Parameters

NumberOfHeaps

Specifies the maximum number of heap handles that can be stored into the buffer pointed to by ProcessHeaps.

ProcessHeaps

Points to a buffer to receive an array of heap handles.

Return Value

The return value is the number of heap handles that are valid for the calling process.

If the return value is less than or equal to NumberOfHeaps, it is also the number of heap handles stored into the buffer pointed to by ProcessHeaps.

If the return value is greater than NumberOfHeaps, the buffer pointed to by ProcessHeaps is too small to hold all the valid heap handles of the calling process.The function will have stored no handles into that buffer. In this situation, use the return value to allocate a buffer that is large enough to receive the handles, and call the function again.

If the return value is zero, the function has failed, because every Win32 process has at least one valid heap, the process heap. To get extended error information, call GetLastError.

Remarks

Use the GetProcessHeap function to obtain a handle to the process heap of the calling process. The GetProcessHeaps function obtains a handle to that heap, plus handles to any additional private heaps created by calling the HeapCreate function.

See Also

GetProcessHeap , HeapCreate


GetProcessShutdownParameters

The GetProcessShutdownParameters function retrieves shutdown parameters for the currently calling process.

BOOL GetProcessShutdownParameters(

LPDWORD  lpdwLevel,	// shutdown priority
LPDWORD  lpdwFlags	// shutdown flag
);
Parameters

lpdwLevel

Points to a variable that receives the shutdown priority level. Higher levels shut down first. System level shutdown orders are reserved for system components. Higher numbers shut down first. Following are the level conventions:

Value	Meaning
000−0FF	System reserved last shutdown range.
100−1FF	Application reserved last shutdown range.
200−2FF	Application reserved "in between" shutdown range.
300−3FF	Application reserved first shutdown range.
400−4FF	System reserved first shutdown range.
All processes start at shutdown level 0x280.

lpdwFlags

Points to a variable that receives the shutdown flags. It can be the following value:

Value	Meaning
SHUTDOWN_NORETRY	If this process takes longer than the specified timeout to shut down, do not display a retry dialog box for the user. Instead, just cause the process to directly exit.
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

SetProcessShutdownParameters


GetProcessTimes

The GetProcessTimes function obtains timing information about a specified process.

BOOL GetProcessTimes(

HANDLE  hProcess,	// specifies the process of interest
LPFILETIME  lpCreationTime,	// when the process was created
LPFILETIME  lpExitTime,	// when the process exited
LPFILETIME  lpKernelTime,	// time the process has spent in kernel mode
LPFILETIME  lpUserTime	// time the process has spent in user mode
);
Parameters

hProcess

An open handle that specifies the process whose timing information is sought. This handle must be created with PROCESS_QUERY_INFORMATION access.

lpCreationTime

Points to a FILETIME structure that receives the creation time of the process.

lpExitTime

Points to a FILETIME structure that receives the exit time of the process. If the process has not exited, the content of this structure is undefined.

lpKernelTime

Points to a FILETIME structure that receives the amount of time that the process has executed in kernel mode. The time that each of the threads of the process has executed in kernel mode is determined, and then all of those times are summed together to obtain this value.

lpUserTime

Points to a FILETIME structure that receives the amount of time that the process has executed in user mode. The time that each of the threads of the process has executed in user mode is determined, and then all of those times are summed together to obtain this value.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

All times are expressed using FILETIME data structures. Such a structure contains two 32-bit values that combine to form a 64-bit count of 100-nanosecond time units.

Process creation and exit times are points in time expressed as the amount of time that has elapsed since midnight on January 1, 1601 at Greenwich, England. The Win32 API provides several functions that an application can use to convert such values to more generally useful forms.

Process kernel mode and user mode times are amounts of time. For example, if a process has spent one second in kernel mode, this function will fill the FILETIME structure specified by lpKernelTime with a 64-bit value of ten million. That is the number of 100-nanosecond units in one second.

See Also

FILETIME, FileTimeToDosDateTime, FileTimeToLocalFileTime, FileTimeToSystemTime


GetProcessVersion  (preliminaryWindows NT)
GetProcessVersion (preliminary−Windows NT)

The GetProcessVersion function obtains the major and minor version numbers of the Windows version on which a specified process expects to run.

DWORD GetProcessVersion(

DWORD  ProcessId	// identifier specifying the process of interest
);
Parameters

ProcessId

Process identifier that specifies the process of interest. A ProcessId value of zero specifies the calling process.

Return Value

If the function succeeds, the return value is the version of Windows on which the process expects to run. The high word of the return value contains the major version number. The low word of the return value contains the minor version number.

If the function fails, the return value is zero. To get extended error information, call GetLastError. The function fails if ProcessId is an invalid value.

Remarks

The GetProcessVersion function performs less quickly when ProcessId is nonzero, specifying a process other than the calling process.

The version number returned by this function is the version number stamped in the image header of the .EXE file the process is running. Linker programs set this value.


GetProcessWindowStation

The GetProcessWindowStation function returns a handle of the window station associated with the calling process.

HWINSTA GetProcessWindowStation(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is a handle of the window station associated with the calling process.

If the function fails, the return value is NULL. This can occur if the calling process is not an application written for Windows NT. To get extended error information, call GetLastError.

Remarks

The system associates a window station with a process when the process is created. A process can use the SetProcessWindowStation function to change its window station.

The calling process can use the returned handle in calls to the GetUserObjectInformation, GetUserObjectSecurity, SetUserObjectInformation, and SetUserObjectSecurity functions.

See Also

GetThreadDesktop, GetUserObjectInformation, GetUserObjectSecurity, SetProcessWindowStation, SetUserObjectInformation, SetUserObjectSecurity


GetProcessWorkingSetSize

The GetProcessWorkingSetSize function obtains the minimum and maximum working set sizes of a specified process.

The "working set" of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault. The size of a process' working set is specified in bytes. The minimum and maximum working set sizes affect the virtual memory paging behavior of a process.

BOOL GetProcessWorkingSetSize(

HANDLE  hProcess,	// open handle to the process of interest
LPDWORD  lpMinimumWorkingSetSize,	// points to variable to receive minimum working set size
LPDWORD  lpMaximumWorkingSetSize	// points to variable to receive maximum working set size
);
Parameters

hProcess

An open handle to the process whose working set sizes will be obtained. The handle must have PROCESS_QUERY_INFORMATION access rights.

lpMinimumWorkingSetSize

Points to a variable that receives the minimum working set size of the specified process. The virtual memory manager attempts to keep at least this much memory resident in the process whenever the process is active.

lpMaximumWorkingSetSize

Points to a variable that receives the maximum working set size of the specified process. The virtual memory manager attempts to keep no more than this much memory resident in the process whenever the process is active when memory is in short supply.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

SetProcessWorkingSetSize


GetProfileInt

The GetProfileInt function retrieves an integer from the specified key name in the given section of the WIN.INI file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

UINT GetProfileInt(

LPCTSTR  lpAppName,	// address of section name
LPCTSTR  lpKeyName,	// address of key name
INT  nDefault	// default value if key name is not found
);
Parameters

lpAppName

Points to a null-terminated string that specifies the section containing the key name.

lpKeyName

Points to the null-terminated string containing the key name whose value is to be retrieved. This value is in the form of a string; the GetProfileInt function converts the string into an integer and returns the integer.

nDefault

Specifies the default value to return if the key name cannot be found in the initialization file..

Return Value

If the function succeeds, the return value is the integer equivalent of the string following the key name in WIN.INI. If the function cannot find the key, the return value is the default value. If the value of the key is less than zero, the return value is zero.

Remarks

If the key name consists of digits followed by characters that are not numeric, the function returns only the value of the digits. For example, the function returns 102 for the following line: KeyName=102abc.

Windows NT: Calls to profile functions may be mapped to the registry instead of to the initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

When the operation has been mapped, the GetProfileInt function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

GetPrivateProfileInt, WriteProfileString


GetProfileSection

The GetProfileSection function retrieves all of the keys and values for the specified section of the WIN.INI file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

Windows 95

The specified profile section must not exceed 32K.

Windows NT

The specified profile section has no size limit.

DWORD GetProfileSection(

LPCTSTR  lpAppName,	// address of section name
LPTSTR  lpReturnedString,	// address of return buffer
DWORD  nSize	// size of return buffer
);
Parameters

lpAppName

Points to a null-terminated string containing the section name in the WIN.INI file.

lpReturnedString

Points to a buffer that receives the keys and values associated with the named section. The buffer is filled with one or more null-terminated strings; the last string is followed by a second null character.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpReturnedString parameter.

Windows 95

The maximum buffer size is 32,767 characters.

Windows NT

There is no maximum buffer size.

Return Value

The return value specifies the number of characters copied to the specified buffer, not including the terminating null character. If the buffer is not large enough to contain all the keys and values associated with the named section, the return value is equal to the length specified by nSize minus two.

Remarks

The format of the returned keys and values is one or more null-terminated strings, followed by a final null character. Each string has the following form:

key=string

The GetProfileSection function is not case-sensitive; the strings can be a combination of uppercase and lowercase letters.

This operation is atomic; no updates to the WIN.INI file are allowed while the keys and values for the section are being copied to the buffer.

Windows NT: Calls to profile functions may be mapped to the registry instead of to the initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

When the operation has been mapped, the GetProfileSection function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

GetPrivateProfileSection, WriteProfileSection


GetProfileString

The GetProfileString function retrieves the string associated with the specified key in the given section of the WIN.INI file. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

DWORD GetProfileString(

LPCTSTR  lpAppName,	// address of section name
LPCTSTR  lpKeyName,	// address of key name
LPCTSTR  lpDefault,	// address of default string
LPTSTR  lpReturnedString,	// address of destination buffer
DWORD  nSize	// size of destination buffer
);
Parameters

lpAppName

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.

lpKeyName

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.

lpDefault

Points to the default value for the given key if the key cannot be found in the initialization file. This parameter cannot be NULL.

lpReturnedString

Points to a buffer that receives the character string.

nSize

Specifies the size, in characters, of the buffer pointed to by the lpReturnedString parameter.

Return Value

If the function succeeds, the return value is the number of characters copied to the buffer, not including the null-terminating character.

If neither lpAppName nor lpKeyName is NULL and the supplied destination buffer is too small to hold the requested string, the string is truncated and followed by a null character, and the return value is equal to nSize minus one.

If either lpAppName or lpKeyName is NULL and the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters. In this case, the return value is equal to nSize minus two.

Remarks

If the string associated with the lpKeyName parameter is enclosed in single or double quotation marks, the marks are discarded when the GetProfileString function returns the string.

The GetProfileString function is not case-sensitive; the strings can contain a combination of uppercase and lowercase letters.

A section in the WIN.INI file must have the following form:

[section]
key=string
      .
      .
      .

An application can use the GetPrivateProfileString function to retrieve a string from a specified initialization file.

The lpDefault parameter must point to a valid string, even if the string is empty (that is, even if its first character is a null character).

Windows NT: Calls to profile functions may be mapped to the registry instead of to the initialization files. This mapping occurs when the initialization file and section are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

When the operation has been mapped, the GetProfileString function retrieves information from the registry, not from the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

GetPrivateProfileString, WriteProfileString


GetProp

The GetProp function retrieves a data handle from the property list of the given window. The given character string identifies the handle to be retrieved. The string and handle must have been added to the property list by a previous call to the SetProp function.

HANDLE GetProp(

HWND  hWnd,	// handle of window
LPCTSTR  lpString	// atom or address of string
);
Parameters

hWnd

Identifies the window whose property list is to be searched.

lpString

Points to a null-terminated character string or contains an atom that identifies a string. If this parameter is an atom, it must have been created by using the AddAtom function. The atom, a 16-bit value, must be placed in the low-order word of the lpString parameter; the high-order word must be zero.

Return Value

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


getprotobynam  [image] e

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

struct protoent FAR * PASCAL FAR getprotobyname(

const char FAR * name
);
Parameters

name

A pointer to a protocol name.

Return Value

If the function succeeds, getprotobyname returns a pointer to the protoent structure described previously.

If the function fails, it returns a NULL pointer. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
Remarks

The getprotobyname function returns a pointer to the following structure, which contains the name(s) and protocol number that correspond to the given protocol name.

struct protoent {

    char FAR *        p_name;

    char FAR * FAR *  p_aliases;

    short             p_proto;

};

The members of this structure are:

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

See Also

getprotobynumber, WSAAsyncGetProtoByName, WSACancelBlockingCall, WSAStartup


getprotobynumber

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

struct protoent FAR * PASCAL FAR getprotobynumber(

int proto
);
Parameters

proto

A protocol number, in host byte order.

Return Value

If the function succeeds, getprotobynumber returns a pointer to the protoent structure described previously.

If the function fails, it returns NULL. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
Remarks

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

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

See Also

getprotobyname, WSAAsyncGetProtoByNumber, WSACancelBlockingCall, WSAStartup,


GetQueuedCompletionStatus

The GetQueuedCompletionStatus function attempts to dequeue an I/O completion packet from a specified input/output completion port. If there is no completion packet queued, the function waits for a pending input/output operation associated with the completion port to complete. The function returns when it can dequeue a completion packet, or optionally when the function times out. If the function returns because of an I/O operation completion, it sets several variables that provide information about the operation.

BOOL GetQueuedCompletionStatus(

HANDLE CompletionPort,	// the I/O completion port of interest
LPDWORD lpNumberOfBytesTransferred,	// to receive number of bytes transferred during I/O
LPDWORD lpCompletionKey,	// to receive file's completion key
LPOVERLAPPED * lpOverlapped,	// to receive pointer to OVERLAPPED structure
DWORD dwMilliseconds	// optional timeout value
);
Parameters

CompletionPort

Handle to the input/output completion port of interest. Use the CreateIoCompletionPort function to create I/O completion ports.

lpNumberOfBytesTransferred

Points to a variable that the function sets to the number of bytes transferred during an I/O operation that has completed and is causing the function to return.

lpCompletionKey

Points to a variable that the function sets to the completion key value associated with the file handle whose I/O operation has completed and is causing the function to return. A completion key is a per-file key that is specified in a call to CreateIoCompletionPort.

lpOverlapped

Points to a variable that the function sets to the address of the OVERLAPPED structure that was specified when an input/output operation that has completed was started.

The following functions can be used to start input/output operations that complete using I/O completion ports. You must pass the function an OVERLAPPED structure and a file handle associated (by a call to CreateIoCompletionPort) with an I/O completion port to invoke the I/O completion port mechanism:

•	ConnectNamedPipe

•	DeviceIoControl

•	LockFileEx

•	ReadFile

•	TransactNamedPipe

•	WaitCommEvent

•	WriteFile

Even if both of the preceding conditions (passing the function a file handle associated with a completion port and a valid OVERLAPPED structure) are met, an application can prevent completion port notification. To do this, specify a valid event handle for the hEvent member of the OVERLAPPED structure, and set the low order bit of that event handle. A valid event handle whose low order bit is set keeps I/O completion from being queued to the completion port.

dwMilliseconds

Specifies the number of milliseconds that the caller is willing to wait for an input/output completion packet to appear at the I/O completion port. If a completion packet doesn't appear within the specified time, the function times out, returns FALSE, and sets *lpOverlapped to NULL.

Timing out is optional. If dwMilliseconds is -1, the function will never time out. If dwMilliseconds is zero and there is no I/O operation to dequeue, the function will timeout immediately.

Return Value

The GetQueuedCompletionStatus function's return value is TRUE if the function dequeues an I/O completion packet for a successful I/O operation from the completion port. The function stores valid values into the variables pointed to by lpNumberOfBytesTransferred, lpCompletionKey, and lpOverlapped.

The function's return value is FALSE, and *lpOverlapped is set to NULL, if the function does not dequeue an I/O completion packet from the completion port. The function does not store valid values into the variables pointed to by lpNumberOfBytesTransferred and lpCompletionKey. To get extended error information, call GetLastError.

The function's return value is FALSE, and *lpOverlapped is not NULL, if the function dequeues an I/O completion packet for a failed I/O operation from the completion port. The function stores valid values into the variables pointed to by lpNumberOfBytesTransferred, lpCompletionKey, and lpOverlapped. To get extended error information, call GetLastError.

Remarks

The Win32 I/O system can be instructed to send I/O completion notification packets to input/output completion ports, where they are queued up. The CreateIoCompletionPort function provides a mechanism for this.

When you perform an input/output operation with a file handle that has an associated input/output completion port, the I/O system sends a completion notification packet to the completion port when the I/O operation completes. The I/O completion port places the completion packet in a first-in-first-out queue. The GetQueuedCompletionStatus function retrieves these queued I/O completion packets.

A server application may have several threads calling GetQueuedCompletionStatus for the same completion port. As input operations complete, the operating system queues completion packets to the completion port. If threads are actively waiting in a call to this function, queued requests complete their call.

You can call the PostQueuedCompletionStatus function to post an I/O completion packet to an I/O completion port. The I/O completion packet will satisfy an outstanding call to the GetQueuedCompletionStatus function.

See Also

ConnectNamedPipe, CreateIoCompletionPort, DeviceIoControl, LockFileEx, OVERLAPPED, ReadFile, PostQueuedCompletionStatus, TransactNamedPipe, WaitCommEvent, WriteFile,


GetQueueStatus

The GetQueueStatus function returns flags that indicate the type of messages found in the calling thread's message queue.

DWORD GetQueueStatus(

UINT  flags	// queue-status flags
);
Parameters

flags

Specifies queue-status flags giving the types of messages to check for. This parameter can be a combination of the following values:

Value	Meaning
QS_ALLEVENTS	An input, WM_TIMER, WM_PAINT, WM_HOTKEY, or posted message is in the queue.
QS_ALLINPUT	Any message is in the queue.
QS_HOTKEY	A WM_HOTKEY message is in the queue.
QS_INPUT	An input message is in the queue.
QS_KEY	A WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, or WM_SYSKEYDOWN message is in the queue.
QS_MOUSE	A WM_MOUSEMOVE message or mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on).
QS_MOUSEBUTTON	A mouse-button message (WM_LBUTTONUP, WM_RBUTTONDOWN, and so on).
QS_MOUSEMOVE	A WM_MOUSEMOVE message is in the queue.
QS_PAINT	A WM_PAINT message is in the queue.
QS_POSTMESSAGE	A posted message (other than those just listed) is in the queue.
QS_SENDMESSAGE	A message sent by another thread or application is in the queue.
QS_TIMER	A WM_TIMER message is in the queue.
Return Value

The high-order word of the return value indicates the types of messages currently in the queue. The low-order word indicates the types of messages that have been added to the queue and that are still in the queue since the last call to the GetQueueStatus, GetMessage, or PeekMessage function.

Remarks

The presence of a QS_ flag in the return value does not guarantee that a subsequent call to the PeekMessage or GetMessage function will return a message. GetMessage and PeekMessage perform some internal filtering that may cause the message to be processed internally. For this reason, the return value from GetQueueStatus should be considered only a hint as to whether GetMessage or PeekMessage should be called.

See Also

GetInputState, GetMessage, PeekMessage


GetRasterizerCaps

The GetRasterizerCaps function returns flags indicating whether TrueType fonts are installed in the system.

BOOL GetRasterizerCaps(

LPRASTERIZER_STATUS  lprs,	// address of rasterizer information structure
UINT  cb	// number of bytes in structure
);
Parameters

lprs

Points to a RASTERIZER_STATUS structure to receive information about the rasterizer.

cb

Specifies the number of bytes to be copied into the structure pointed to by the lprs parameter.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The GetRasterizerCaps function enables applications and printer drivers to determine whether TrueType fonts are installed.

If the TT_AVAILABLE flag is set in the wFlags member of the RASTERIZER_STATUS structure, at least one TrueType font is installed. If the TT_ENABLED flag is set, TrueType is enabled for the system.

The actual number of bytes copied is either the member specified in the cb parameter or the length of the RASTERIZER_STATUS structure, whichever is less.

See Also

GetOutlineTextMetrics, RASTERIZER_STATUS


GetRegionData

The GetRegionData function fills the specified buffer with data describing a region. This data includes the dimensions of the rectangles that make up the region.

DWORD GetRegionData(

HRGN  hRgn,	// handle of region
DWORD  dwCount,	// size of buffer containing region data
LPRGNDATA  lpRgnData	// address of buffer containing region data
);
Parameters

hRgn

Identifies the region.

dwCount

Specifies the size, in bytes, of the lpRgnData buffer.

lpRgnData

Points to a RGNDATA structure that receives the information. If this parameter is NULL, the return value contains the number of bytes needed for the region data.

Return Value

If the function succeeds and dwCount specifies an adequate number of bytes, the return value is 1. If dwCount is too small or lpRgnData is NULL, the return value is the required number of bytes.

If the function fails, the return value is zero.

Remarks

The GetRegionData function is used in conjunction with the ExtCreateRegion function.

See Also

ExtCreateRegion, RGNDATA


GetResourceID

The GetResourceID function determines whether the specified file or pipe depends on a network connection.

DWORD GetResourceID(

USHORT
);
Parameters

hNetHandle

Handle to an open file or pipe.

Return Value

Returns a network identifier if the specified file or pipe depends on it, 0 otherwise.


GetRgnBox

The GetRgnBox function retrieves the bounding rectangle of the specified region.

int GetRgnBox(

HRGN  hrgn,	// handle of a region
LPRECT  lprc	// address of structure that receives bounding rect.
);
Parameters

hrgn

Identifies the region.

lprc

Points to a RECT structure that receives the bounding rectangle.

Return Value

The return value specifies the region's complexity. It can be one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than a single rectangle.
If the hrgn parameter does not identify a valid region, the return value is zero.

See Also

RECT


GetROP2

The GetROP2 function retrieves the foreground mix mode of the specified device context. The mix mode specifies how the pen or interior color and the color already on the screen are combined to yield a new color.

int GetROP2(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value specifies the foreground mix mode.

If the function fails, the return value is zero.

Remarks

Following are the foreground mix modes:

Mix mode	Description
R2_BLACK	Pixel is always 0.
R2_COPYPEN	Pixel is the pen color.
R2_MASKNOTPEN	Pixel is a combination of the colors common to both the screen and the inverse of the pen.
R2_MASKPEN	Pixel is a combination of the colors common to both the pen and the screen.
R2_MASKPENNOT	Pixel is a combination of the colors common to both the pen and the inverse of the screen.
R2_MERGENOTPEN	Pixel is a combination of the screen color and the inverse of the pen color.
R2_MERGEPEN	Pixel is a combination of the pen color and the screen color.
R2_MERGEPENNOT	Pixel is a combination of the pen color and the inverse of the screen color.
R2_NOP	Pixel remains unchanged.
R2_NOT	Pixel is the inverse of the screen color.
R2_NOTCOPYPEN	Pixel is the inverse of the pen color.
R2_NOTMASKPEN	Pixel is the inverse of the R2_MASKPEN color.
R2_NOTMERGEPEN	Pixel is the inverse of the R2_MERGEPEN color.
R2_NOTXORPEN	Pixel is the inverse of the R2_XORPEN color.
R2_WHITE	Pixel is always 1.
R2_XORPEN	Pixel is a combination of the colors in the pen and in the screen, but not in both.
See Also

SetROP2


GetSaveFileName

The GetSaveFileName function creates a system-defined dialog box that enables the user to select a file to save.

BOOL GetSaveFileName(

LPOPENFILENAME  lpofn	// address of structure with initialization data
);
Parameters

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.

Return Value

If the user selects a file to save, the return value is TRUE.

The return value 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.

To get extended error information, call CommDlgExtendedError. CommDlgExtendedError may return one of the following error codes:

CDERR_FINDRESFAILURE	CDERR_NOHINSTANCE
CDERR_INITIALIZATION	CDERR_NOHOOK
CDERR_LOCKRESFAILURE	CDERR_NOTEMPLATE
CDERR_LOADRESFAILURE	CDERR_STRUCTSIZE
CDERR_LOADSTRFAILURE	FNERR_BUFFERTOOSMALL
CDERR_MEMALLOCFAILURE	FNERR_INVALIDFILENAME
CDERR_MEMLOCKFAILURE	FNERR_SUBCLASSFAILURE
Remarks

If the hook function (pointed to by the lpfnHook member of the OPENFILENAME structure) processes the WM_CTLCOLORDLG message, GetSaveFileName must return a handle for the brush that should be used to paint the control background.

Ending the dialog box from within the hook function by calling the EndDialog function prevents the COMDLG32.DLL dynamic-link library (DLL) from properly exiting its worker thread. For applications that dynamically load or unload COMDLG32.DLL, this type of exiting may result in an access violation during unloading as the worker thread's address space is invalidated.

See Also

CommDlgExtendedError, GetOpenFilename, OPENFILENAME, WM_CTLCOLORDLG


GetScrollInfo  (preliminaryWindows NT)
GetScrollInfo  (preliminary−Windows NT)

The GetScrollInfo function retrieves the parameters of a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (thumb).

BOOL GetScrollInfo(

HWND  hwnd,	// handle of window with scroll bar
int  fnBar,	// scroll bar flag
LPSCROLLINFO  lpsi	// pointer to structure for scroll parameters
);
Parameters

hwnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the fnBar parameter.

fnBar

Specifies the type of scroll bar for which to retrieve parameters. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Retrieves the parameters for a scroll bar control. The hwnd parameter must be the handle of the scroll bar control.
SB_HORZ	Retrieves the parameters for the given window's standard horizontal scroll bar.
SB_VERT	Retrieves the parameters for the given window's standard vertical scroll bar.
lpsi

Points to a SCROLLINFO structure whose fMask member, upon entry to the function, specifies the scroll bar parameters to retrieve. Before returning, the function copies the specified parameters to the appropriate members of the structure.

The fMask member can be a combination of the following values:

Value	Meaning
SIF_PAGE	Copies the scroll page to the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS	Copies the scroll position to the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE	Copies the scroll range to the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
Return Value

If the function retrieved any values, the return value is TRUE.

If the function does not retrieve any values, the return value is FALSE.

Remarks

The GetScrollInfo function enables applications to use 32-bit scroll positions. Although the messages that indicate scroll-bar position, WM_HSCROLL and WM_VSCROLL, provide only 16 bits of position data, the functions SetScrollInfo and GetScrollInfo provide 32 bits of scroll-bar position data. Thus, an application can call GetScrollInfo while processing either the WM_HSCROLL or WM_VSCROLL messages to obtain 32-bit scroll-bar position data.

The limitation on this technique applies to real-time scrolling of a window's contents. An application implements real-time scrolling by processing the WM_HSCROLL or WM_VSCROLL messages that carry the SB_THUMBTRACK notification value, thereby tracking the position of the scroll box (thumb) as the user moves it. Unfortunately, there is no function to retrieve the 32-bit position scroll-box position as the user moves the scroll box. Because GetScrollInfo provides only the static position, an application can obtain only 32-bit position data before or after a scroll operation.

See Also

SCROLLINFO, SetScrollInfo, WM_HSCROLL, WM_VSCROLL


GetScrollPos

The GetScrollPos function retrieves the current position of the scroll box (thumb) in the specified scroll bar. The current position is a relative value that depends on the current scrolling range. For example, if the scrolling range is 0 through 100 and the scroll box is in the middle of the bar, the current position is 50.

int GetScrollPos(

HWND  hWnd,	// handle of window with scroll bar
int  nBar	// scroll bar flags
);
Parameters

hWnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the nBar parameter.

nBar

Specifies the scroll bar to be examined. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Retrieves the position of the scroll box in a scroll bar control. The hWnd parameter must be the handle of the scroll bar control.
SB_HORZ	Retrieves the position of the scroll box in a window's standard horizontal scroll bar.
SB_VERT	Retrieves the position of the scroll box in a window's standard vertical scroll bar.
Return Value

If the function succeeds, the return value is the current position of the scroll box/

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetScrollPos function enables applications to use 32-bit scroll positions. Although the messages that indicate scroll bar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data, the functions SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange support 32-bit scroll bar position data. Thus, an application can call GetScrollPos while processing either the WM_HSCROLL or WM_VSCROLL messages to obtain 32-bit scroll bar position data.

The limitation on this technique applies to real-time scrolling of a window's content. An application implements such scrolling by processing the WM_HSCROLL or WM_VSCROLL messages that carry the SB_THUMBTRACK notification message, thereby tracking the position of the scroll box, also known as the thumb, while the user moves it. Unfortunately, there is no function to retrieve the thumb's 32-bit position while the user moves it. GetScrollPos provides static position data only; an application can therefore only obtain 32-bit position data before or after a scroll has taken place.

See Also

GetScrollRange, ScrollDC, ScrollWindow, SetScrollPos, SetScrollRange, WM_HSCROLL, WM_VSCROLL


GetScrollRange

The GetScrollRange function retrieves the current minimum and maximum scroll box (thumb) positions for the specified scroll bar.

For Windows 95, the GetScrollRange function exists for compatibility with operating system versions earlier than 4.0. With version 4.0 or later, use the GetScrollInfo function.

BOOL GetScrollRange(

HWND  hWnd,	// handle of window with scroll bar
int  nBar,	// scroll bar flags
LPINT  lpMinPos,	// address of variable that receives minimum position
LPINT  lpMaxPos	// address of variable that receives maximum position
);
Parameters

hWnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the nBar parameter.

nBar

Specifies the scroll bar from which the positions are retrieved. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Retrieves the positions of a scroll bar control. The hWnd parameter must be the handle of the scroll bar control.
SB_HORZ	Retrieves the positions of the window's standard horizontal scroll bar.
SB_VERT	Retrieves the positions of the window's standard vertical scroll bar.
lpMinPos

Points to the integer variable that receives the minimum position.

lpMaxPos

Points to the integer variable that receives the maximum position.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the specified window does not have standard scroll bars or is not a scroll bar control, the GetScrollRange function copies zero to the lpMinPos and lpMaxPos parameters.

The default range for a standard scroll bar is 0 through 100. The default range for a scroll bar control is empty (both values are zero).

The messages that indicate scroll bar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data. However, because SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier for the WM_HSCROLL and WM_VSCROLL messages. See the GetScrollPos function for a description of the technique and its limits.

See Also

GetScrollPos, SetScrollPos, SetScrollRange, WM_HSCROLL, WM_VSCROLL


GetSecurityDescriptorControl

The GetSecurityDescriptorControl function retrieves a security descriptor's control and revision information.

BOOL GetSecurityDescriptorControl(

PSECURITY_DESCRIPTOR  pSecurityDescriptor,	// address of security descriptor
PSECURITY_DESCRIPTOR_CONTROL  pControl,	// address of  control structure
LPDWORD  lpdwRevision	// address of revision value
);
Parameters

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure whose control and revision information the function retrieves.

pControl

Points to a SECURITY_DESCRIPTOR_CONTROL structure receiving the security descriptor's control information.

lpdwRevision

Points to a variable receiving the security descriptor's revision value. This value is always set, even when GetSecurityDescriptorControl returns an error.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL


GetSecurityDescriptorDacl

The GetSecurityDescriptorDacl function retrieves a pointer to the discretionary access-control list (ACL) in a specified security descriptor.

BOOL GetSecurityDescriptorDacl(

PSECURITY_DESCRIPTOR  pSecurityDescriptor,	// address of security descriptor
LPBOOL  lpbDaclPresent,	// address of flag for presence of disc. ACL
PACL  *pDacl,	// address of pointer to ACL
LPBOOL  lpbDaclDefaulted	// address of flag for default disc. ACL
);
Parameters

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure containing the discretionary ACL. The function retrieves a pointer to it.

lpbDaclPresent

Points to a flag the function sets to indicate the presence of a discretionary ACL in the specified security descriptor. If this parameter is TRUE, the security descriptor contains a discretionary ACL, and the remaining output parameters in this function receive valid values. If this parameter is FALSE, the security descriptor does not contain a discretionary ACL, and the remaining output parameters do not receive valid values.

pDacl

Points to a pointer to an ACL structure. If a discretionary ACL exists, the function sets the pointer pointed to by pDacl to the address of the security descriptor's discretionary ACL. If a discretionary ACL does not exist, no value is stored.

If the function stores a NULL value in the pointer pointed to by pDacl, the security descriptor has a NULL discretionary ACL. A NULL discretionary ACL implicitly allows all access to an object.

lpbDaclDefaulted

Points to a flag set to the value of the SE_DACL_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure if a discretionary ACL exists for the security descriptor. If this flag is TRUE, the discretionary ACL was retrieved by a default mechanism; if FALSE, the discretionary ACL was explicitly specified by a user.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

ACL, GetSecurityDescriptorControl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorDacl


GetSecurityDescriptorGroup

The GetSecurityDescriptorGroup function retrieves the primary group information from a security descriptor.

BOOL GetSecurityDescriptorGroup(

PSECURITY_DESCRIPTOR  pSecurityDescriptor,	// address of security descriptor
PSID *  pGroup,	// address of pointer to group security identifier (SID)
LPBOOL  lpbGroupDefaulted	// address of flag for default
);
Parameters

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure whose primary group information the function retrieves.

pGroup

Points to a pointer to a SID structure identifying the primary group when the function returns. (A SID is a security identifier.) If the security descriptor does not contain a primary group, the function sets the pointer pointed to by pGroup to NULL and ignores the remaining output parameter, lpbGroupDefaulted. If the security descriptor contains a primary group, the function sets the pointer pointed to by pGroup to the address of the security descriptor's group SID structure and provides a valid value for the variable pointed to by lpbGroupDefaulted.

lpbGroupDefaulted

Points to a flag set to the value of the SE_GROUP_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure when the function returns. If the value stored in the variable pointed to by the pGroup parameter is NULL, no value is set.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorGroup, SID


GetSecurityDescriptorLength

The GetSecurityDescriptorLength function returns the length, in bytes, of a structurally valid SECURITY_DESCRIPTOR structure. The length includes the length of all associated structures, such as SID and ACL structures.

DWORD GetSecurityDescriptorLength(

PSECURITY_DESCRIPTOR  pSecurityDescriptor	// address of security descriptor
);
Parameters

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure whose length the function returns. The SECURITY_DESCRIPTOR structure is assumed to be valid.

Return Value

If the function succeeds, the return value is the length, in bytes, of the SECURITY_DESCRIPTOR structure. If the SECURITY_DESCRIPTOR structure is invalid, the return value is undefined.

Remarks

The minimum length of a security descriptor is SECURITY_DESCRIPTOR_MIN_LENGTH. A security descriptor of this length has no associated SID or ACL structures.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR


GetSecurityDescriptorOwner

The GetSecurityDescriptorOwner function retrieves the owner information from a security descriptor.

BOOL GetSecurityDescriptorOwner(

PSECURITY_DESCRIPTOR  pSecurityDescriptor,	// address of security descriptor
PSID  * pOwner,	// address of pointer to owner security identifier (SID)
LPBOOL  lpbOwnerDefaulted	// address of flag for default
);
Parameters

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure whose owner information the function retrieves.

pOwner

Points to a pointer to a SID structure identifying the owner when the function returns. (A SID is a security identifier.) If the security descriptor does not contain an owner, the function sets the pointer pointed to by pOwner to NULL and ignores the remaining output parameter, lpbOwnerDefaulted. If the security descriptor contains an owner, the function sets the pointer pointed to by pOwner to the address of the security descriptor's owner SID structure and provides a valid value for the variable pointed to by lpbOwnerDefaulted.

lpbOwnerDefaulted

Points to a flag set to the value of the SE_OWNER_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure when the function returns. If the value stored in the variable pointed to by the pOwner parameter is NULL, no value is set.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorOwner, SID


GetSecurityDescriptorSacl

The GetSecurityDescriptorSacl function retrieves a pointer to the system access-control list (ACL) in a specified security descriptor.

BOOL GetSecurityDescriptorSacl(

PSECURITY_DESCRIPTOR  pSecurityDescriptor,	// address of security descriptor
LPBOOL  lpbSaclPresent,	// address of flag for presence of system ACL
PACL  *pSacl,	// address of pointer to ACL
LPBOOL  lpbSaclDefaulted	// address of flag for default system ACL
);
Parameters

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure containing the system ACL to which the function retrieves a pointer to.

lpbSaclPresent

Points to a flag the function sets to indicate the presence of a system ACL in the specified security descriptor. If this parameter is TRUE, the security descriptor contains a system ACL, and the remaining output parameters in this function receive valid values. If this parameter is FALSE, the security descriptor does not contain a system ACL, and the remaining output parameters do not receive valid values.

pSacl

Points to a pointer to an ACL structure. If a system ACL exists, the function sets the pointer pointed to by pSacl to the address of the security descriptor's system ACL. If a system ACL does not exist, no value is stored.

If the function stores a NULL value in the pointer pointed to by pSacl, the security descriptor has a NULL system ACL.

lpbSaclDefaulted

Points to a flag set to the value of the SE_SACL_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure if a system ACL exists for the security descriptor.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

ACL, GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorSacl


getservbynam  [image] e

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

struct servent FAR * getservbyname (

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

name

A pointer to a service name.

proto

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

Return Value

If the function succeeds, getservbyname returns a pointer to the servent structure described in getservbyname.

If the function fails, it returns NULL. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
Remarks

The getservbyname function returns a pointer to the following structure, which contains the name(s) and service number that correspond to the given service name.

struct servent {

    char FAR *        s_name;

    char FAR * FAR *  s_aliases;

    short             s_port;

    char FAR *        s_proto;

};

The members of this structure are:

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

See Also

getservbyport, WSAAsyncGetServByName, WSACancelBlockingCall, WSAStartup


getservbyport

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

struct servent FAR * getservbyport (

int port,
const char FAR * proto
);
Parameters

port

The port for a service, in network byte order.

proto

An optional pointer to a protocol name. If this is NULL, getservbyport returns the first service entry that matches the specified port. Otherwise, getservbyport matches both the port and the proto.

Return Value

If the function succeeds, getservbyport returns a pointer to the servent structure described previously.

If the function fails, it returns a NULL pointer. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
Remarks

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

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

See Also

getservbyname, WSAAsyncGetServByPort, WSACancelBlockingCall, WSAStartup


GetService

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

INT GetService(

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

dwNameSpace

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

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

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

lpGuid

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

lpServiceName

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

dwProperties

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

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

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

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

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

lpdwBufferSize

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

lpServiceAsyncInfo

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

Return Value

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

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

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

SetService, NS_SERVICE_INFO, SERVICE_INFO


GetServiceDisplayName

The GetServiceDisplayName function obtains the display name that is associated with a particular service name. The service name is the same as the service's registry key name.

BOOL GetServiceDisplayName(

SC_HANDLE  hSCManager,	// handle to a service control manager database
LPCTSTR  lpServiceName,	// the service name
LPTSTR  lpDisplayName,	// buffer to receive the service's display name
LPDWORD  lpcchBuffer	// size of display name buffer and display name
);
Parameters

hSCManager

Handle to a machine's service control manager database. This parameter is an RPC server handle as returned by the OpenSCManager function.

lpServiceName

Points to a null-terminated service name string. This name is the same as the service's registry key name.

lpDisplayName

Points to a buffer into which the function stores the service's display name as a null-terminated string. If the function fails, this buffer will contain an empty string.

lpcchBuffer

Points to a DWORD that contains the size, in characters, of the buffer pointed to by lpDisplayName. When the function returns, this DWORD contains the size, in characters, of the service's display name, excluding the NULL terminator.

If the buffer pointed to by lpDisplayName is too small to contain the display name, the function stores no data into it. When the function returns, the DWORD pointed to by lpcchBuffer contains the size in characters of the service's display name, excluding the NULL terminator.

Return Value

If the functions succeeds, the return value is TRUE.

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

Remarks

There are two names for a service: the service name, which is the actual name of the service's key in the registry's Services section, and a more user-friendly display name that appears in the Services Control Panel application and is used with the NET START command. The GetServiceDisplayName and GetServiceKeyName functions let an application map one of these names to the other. An application passes a service's registry key name to GetServiceDisplayName, and obtains the service's user-friendly display name. An application passes a service's display name to GetServiceKeyName, and obtains the service's registry key name.

See Also

GetServiceKeyName, OpenSCManager


GetServiceKeyName

The GetServiceKeyName function obtains the service name that is associated with a particular service's display name. The service name is the same as the service's registry key name.

BOOL GetServiceKeyName(

SC_HANDLE  hSCManager,	// handle to a service control manager database
LPCTSTR  lpDisplayName,	// the service's display name
LPTSTR  lpServiceName,	// buffer to receive the service name
LPDWORD  lpcchBuffer	// size of service name buffer and service name
);
Parameters

hSCManager

Handle to a computer's service control manager database. This parameter is a remote procedure call (RPC) server handle as returned by OpenSCManager.

lpDisplayName

Points to a null-terminated service display name string.

lpServiceName

Points to a buffer into which the function stores the service name as a null-terminated string. If the function fails, this buffer will contain an empty string.

lpcchBuffer

Points to a DWORD that contains the size in characters of the buffer pointed to by the lpServiceName parameter. When the function returns, this DWORD contains the size, in characters, of the service name, excluding the NULL terminator.

If the buffer pointed to by lpServiceName is too small to contain the service name, the function stores no data in it. When the function returns, the DWORD pointed to by lpcchBuffer contains the size, in characters, of the service name, excluding the NULL terminator.

Return Value

If the functions succeeds, the return value is TRUE.

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

Remarks

There are two names for a service: the service name, which is the actual name of the service's key in the registry's Services section, and a more user-friendly display name that appears in the Services Control Panel application and is used with the NET START command. The GetServiceDisplayName and GetServiceKeyName functions let an application map one of these names to the other. An application passes a service's registry key name to GetServiceDisplayName, and obtains the service's user-friendly display name. An application passes a service's display name to GetServiceKeyName, and obtains the service's registry key name.

See Also

GetServiceDisplayName, OpenSCManager


GetShortPathName

The GetShortPathName function obtains the short path form of a specified input path.

DWORD GetShortPathName(

LPCTSTR  lpszLongPath,	// points to a null-terminated path
LPTSTR  * lpszShortPath,	// points to a buffer to receive the short form of the path
DWORD  cchBuffer	// specifies the size of the buffer pointed to by lpszShortPath
);
Parameters

lpszLongPath

Points to a null-terminated path string. The function obtains the short form of this path.

lpszShortPath

Points to a buffer to receive the short form of the path specified by lpszLongPath.

cchBuffer

Specifies the size, in characters, of the buffer pointed to by lpszShortPath.

Return Value

If the function succeeds, the return value is the length, in characters, of the string stored in *lpszShortPath, not including the terminating null character.

If the function fails due to *lpszShortPath being too small to contain the short path string, the return value is the size, in characters, of the short path string. You need to call the function with a short path buffer that is at least as large as the short path string.

If the function fails for any other reason, the return value is zero. To get extended error information, call GetLastError.

Remarks

When an application calls this function and specifies a path on a volume that does not support 8.3 aliases, such as HPFS, the function fails with ERROR_INVALID_PARAMETER if the pathname is longer than 67 bytes.

The path specified by lpszLongPath does not have to be a fully qualified path or a long path. The short form may be longer than the specifed path.

If the specified path is already in its short form, there is no need for any conversion, and the function simply copies the specified path to the buffer for the short path.

You can set lpszShortPath to the same value as lpszLongPath; in other words, you can set the buffer for the short path to the address of the input path string.

See Also

GetFullPathName


GetSidIdentifierAuthority

The GetSidIdentifierAuthority function returns the address of the SID_IDENTIFIER_AUTHORITY structure in a specified security identifier (SID).

PSID_IDENTIFIER_AUTHORITY GetSidIdentifierAuthority(

PSID  pSid	// address of SID to query
);
Parameters

pSid

Points to the SID structure for which the address of the SID_IDENTIFIER_AUTHORITY structure is returned.

Return Value

If the function succeeds, the return value is the address of the SID_IDENTIFIER_AUTHORITY structure for the specified SID structure.

If the function fails, the return value is undefined. The function fails if the SID structure pointed to by the pSid parameter is invalid. To get extended error information, call GetLastError.

See Also

GetLengthSid, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, IsValidSid, SID, SID_IDENTIFIER_AUTHORITY


GetSidLengthRequired

The GetSidLengthRequired function returns the length, in bytes, of the buffer required to store a SID structure with a specified number of subauthorities.

DWORD GetSidLengthRequired(

UCHAR  nSubAuthorityCount	// count of subauthorities
);
Parameters

nSubAuthorityCount

Specifies the number of subauthorities to be stored in the SID structure.

Return Value

The return value is the length, in bytes, of the buffer required to store the SID structure. This function cannot fail.

See Also

AllocateAndInitializeSid, GetLengthSid, GetSidIdentifierAuthority, GetSidSubAuthority, GetSidSubAuthorityCount, InitializeSid, IsValidSid, SID


GetSidSubAuthority

The GetSidSubAuthority function returns the address of a specified subauthority in a SID structure. The subauthority value is a relative identifier (RID). A SID is a security identifier.

PDWORD GetSidSubAuthority(

PSID  pSid,	// address of security identifier to query
DWORD  nSubAuthority	// index of subauthority to retrieve
);
Parameters

pSid

Points to the SID structure from which the address of a subauthority is to be returned.

nSubAuthority

Specifies an index value identifying the subauthority array element whose address the function will return. The function performs no validation tests on this value. An application can call the GetSidSubAuthorityCount function to discover the range of acceptable values.

Return Value

If the function succeeds, the return value is the address of the specified SID subauthority. To get extended error information, call GetLastError.

If the function fails, the return value is undefined. The function fails if the specified SID structure is invalid or if the index value specified by the nSubAuthority parameter is out of bounds.

See Also

GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthorityCount, IsValidSid, SID


GetSidSubAuthorityCount

The GetSidSubAuthorityCount function returns the address of the field in a SID structure containing the subauthority count. A SID is a security identifier.

PUCHAR GetSidSubAuthorityCount(

PSID  pSid	// address of security identifier to query
);
Parameters

pSid

Points to the SID structure from which a pointer to the subauthority count is returned.

Return Value

If the function succeeds, the return value is a pointer to the subauthority count for the specified SID structure.

If the function fails, the return value is undefined. The function fails if the specified SID structure is invalid. To get extended error information, call GetLastError.

See Also

GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, IsValidSid, SID


getsockname

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

int getsockname (

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

s

A descriptor identifying a bound socket.

name

Receives the address (name) of the socket.

namelen

The size of the name buffer.

Return Value

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

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEFAULT	The namelen argument is not large enough.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAENOTSOCK	The descriptor is not a socket.
WSAEINVAL	The socket has not been bound to an address with bind.
Remarks

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

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

If a socket was bound to INADDR_ANY, indicating that any of the host's IP addresses should be used for the socket, getsockname will not necessarily return information about the host IP address, unless the socket has been connected with connect or accept. A Windows Sockets application must not assume that the IP address will be changed from INADDR_ANY unless the socket is connected. This is because for a multi-homed host, the IP address that will be used for the socket is unknown unless the socket is connected.

See Also

accept, bind, connect, getpeername, socket, WSAStartup


getsockopt

The Windows Sockets getsockopt function retrieves a socket option.

int getsockopt (

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

s

A descriptor identifying a socket.

level

The level at which the option is defined; the only supported levels are SOL_SOCKET and IPPROTO_TCP.

optname

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

optval

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

optlen

A pointer to the size of the optval buffer.

Return Value

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

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEFAULT	The optlen argument was invalid.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAENOPROTOOPT	The option is unknown or unsupported. In particular, SO_BROADCAST is not supported on sockets of type SOCK_STREAM, while SO_ACCEPTCONN, SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER and SO_OOBINLINE are not supported on sockets of type SOCK_DGRAM.
WSAENOTSOCK	The descriptor is not a socket.
Remarks

The getsockopt function retrieves the current value for a socket option associated with a socket of any type, in any state, and stores the result in optval. Options may exist at multiple protocol levels, but they are always present at the uppermost "socket" level. Options affect socket operations, such as whether an operation blocks or not, the routing of packets, out-of-band data transfer, and so on.

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

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

The following options are supported for getsockopt. The "Type" heading identifies the type of data addressed by optval. The TCP_NODELAY option uses level IPPROTO_TCP; all other options use level SOL_SOCKET.

Value	Type	Meaning
SO_ACCEPTCONN	BOOL	Socket is in listen mode.
SO_BROADCAST	BOOL	Socket is configured for the transmission of broadcast messages.
SO_DEBUG	BOOL	Debugging is enabled.
SO_DONTLINGER	BOOL	If true, the SO_LINGER option is disabled.
SO_DONTROUTE	BOOL	Routing is disabled.
SO_ERROR	int	Retrieve error status and clear.
SO_KEEPALIVE	BOOL	Keepalive messages are being sent.
SO_LINGER	struct linger FAR *	Returns the current linger options.
SO_OOBINLINE	BOOL	Out-of-band data is being received in the normal data stream.
SO_RCVBUF	int	Buffer size for receive operations.
SO_REUSEADDR	BOOL	The socket may be bound to an address that is already in use.
SO_SNDBUF	int	Buffer size for send operations.
SO_TYPE	int	The type of the socket (for example, SOCK_STREAM).
TCP_NODELAY	BOOL	Disables the Nagle algorithm for send coalescing.
BSD options not supported for getsockopt are:

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

See Also

setsockopt, socket, WSAAsyncSelect, WSAStartup


GetStartupInfo

The GetStartupInfo function retrieves the contents of the STARTUPINFO structure that was specified when the calling process was created.

VOID GetStartupInfo(

LPSTARTUPINFO  lpStartupInfo	// address of STARTUPINFO structure
);
Parameters

lpStartupInfo

Points to a STARTUPINFO structure that is filled in by the function.

Return Value

This function does not return a value.

Remarks

The STARTUPINFO structure was specified by the process that created the calling process. It can be used to specify properties associated with the main window of the calling process.

See Also

CreateProcess, STARTUPINFO


GetStdHandle

The GetStdHandle function returns a handle for the standard input, standard output, or standard error device.

HANDLE GetStdHandle(

DWORD  nStdHandle	// input, output, or error device
);
Parameters

nStdHandle

Specifies the device for which to return the handle. This parameter can have one of the following values:

Value	Meaning
STD_INPUT_HANDLE	Standard input handle
STD_OUTPUT_HANDLE	Standard output handle
STD_ERROR_HANDLE	Standard error handle
Return Value

If the function succeeds, the return value is a handle of the specified device.

If the function fails, the return value is the INVALID_HANDLE_VALUE flag. To get extended error information, call GetLastError.

Remarks

Handles returned by GetStdHandle can be used by applications that need to read from or write to the console. When a console is created, the standard input handle is a handle of the console's input buffer, and the standard output and standard error handles are handles of the console's active screen buffer. These handles can be used by the ReadFile and WriteFile functions, or by any of the console functions that access the console input buffer or a screen buffer (for example, the ReadConsoleInput, WriteConsole, or GetConsoleScreenBufferInfo functions).

All handles returned by this function have GENERIC_READ and GENERIC_WRITE access unless the SetStdHandle function has been used to set a standard handle to be some handle with a lesser access.

The standard handles of a process may be redirected by a call to SetStdHandle, in which case GetStdHandle returns the redirected handle. If the standard handles have been redirected, you can specify the CONIN$ value in a call to the CreateFile function to get a handle of a console's input buffer. Similarly, you can specify the CONOUT$ value to get a handle of a console's active screen buffer.

See Also

CreateFile, GetConsoleScreenBufferInfo, ReadConsoleInput, ReadFile, SetStdHandle, WriteConsole, WriteFile


GetStockObject

The GetStockObject function retrieves a handle to one of the predefined stock pens, brushes, fonts, or palettes.

HGDIOBJ GetStockObject(

int  fnObject	// type of stock object
);
Parameters

fnObject

Specifies the type of stock object. This parameter can be any one of the following values:

Value	Meaning
BLACK_BRUSH	Black brush.
DKGRAY_BRUSH	Dark gray brush.
GRAY_BRUSH	Gray brush.
HOLLOW_BRUSH	Hollow brush (equivalent to NULL_BRUSH).
LTGRAY_BRUSH	Light gray brush.
NULL_BRUSH	Null brush (equivalent to HOLLOW_BRUSH).
WHITE_BRUSH	White brush.
BLACK_PEN	Black pen.
NULL_PEN	Null pen.
WHITE_PEN	White pen.
ANSI_FIXED_FONT	Windows fixed-pitch (monospace) system font.
ANSI_VAR_FONT	Windows variable-pitch (proportional space) system font.
DEVICE_DEFAULT_FONT	Windows NT only: Device-dependent font.
DEFAULT_GUI_FONT	Windows 95 only: Default font for user interface objects such as menus and dialog boxes.
OEM_FIXED_FONT	Original equipment manufacturer (OEM) dependent fixed-pitch (monospace) font.
SYSTEM_FONT	System font. By default, Windows uses the system font to draw menus, dialog box controls, and text. In Windows versions 3.0 and later, the system font is a proportionally spaced font; earlier versions of Windows used a monospace system font.
SYSTEM_FIXED_FONT	Fixed-pitch (monospace) system font used in Windows versions earlier than 3.0. This stock object is provided for compatibility with earlier versions of Windows.
DEFAULT_PALETTE	Default palette. This palette consists of the static colors in the system palette.
Return Value

If the function succeeds, the return value identifies the logical object requested.

If the function fails, the return value is NULL.

Remarks

Use the DKGRAY_BRUSH, GRAY_BRUSH, and LTGRAY_BRUSH stock objects only in windows with the CS_HREDRAW and CS_VREDRAW styles. Using a gray stock brush in any other style of window can lead to misalignment of brush patterns after a window is moved or sized. The origins of stock brushes cannot be adjusted.

The HOLLOW_BRUSH and NULL_BRUSH stock objects are equivalent.

The font used by the DEFAULT_GUI_FONT stock object could change. Use this stock object when you want to use the font that menus, dialog boxes, and other user interface objects use.

It is not necessary (but it is not harmful) to delete stock objects by calling DeleteObject.

See Also

DeleteObject, SelectObject


GetStretchBltMode

The GetStretchBltMode function retrieves the current stretching mode. The stretching mode defines how color data is added to or removed from bitmaps that are stretched or compressed when the StretchBlt function is called.

int GetStretchBltMode(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value is the current stretching mode.

If the function fails, the return value is zero.

See Also

SetStretchBltMode, StretchBlt


GetStringTypeA

The GetStringTypeA function returns character-type information for the characters in the specified source string. For each character in the string, the function sets one or more bits in the corresponding 16-bit element of the output array. Each bit identifies a given character type, such as whether the character is a letter, a digit, or neither.

BOOL GetStringTypeA(

LCID  Locale,	// locale identifer
DWORD  dwInfoType,	// information-type options
LPCSTR  lpSrcStr,	// pointer to the source string
int  cchSrc,	// size, in bytes, of the source string
LPWORD  lpCharType	// pointer to the buffer for output
);
Parameters

Locale

Specifies the locale identifier. This value uniquely defines the ANSI code page to use to translate the string pointed to by lpSrcStr from ANSI to Unicode. The function then analyzes each Unicode character for character type information.

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale
LOCALE_USER_DEFAULT	Default user locale
Note that the Locale parameter does not exist in the GetStringTypeW function. Because of that parameter difference, an application cannot automatically invoke the proper A or W version of GetStringType* through the use of the #define UNICODE switch. An application can circumvent this limitation by using GetStringTypeEx, which is the recommended Win32 function.

dwInfoType

Specifies the type of character information the user wants to retrieve. The various types are divided into different levels (see the following Remarks section for a list of the information included in each type). This parameter can specify one of the following character type flags:

CT_CTYPE1	Retrieve character type information.
CT_CTYPE2	Retrieve bidirectional layout information.
CT_CTYPE3	Retrieve text processing information.
lpSrcStr

Points to the string for which character types are requested. If cchSrc is −1, the string is assumed to be null terminated. This must be an ANSI string. Note that this can be a double-byte character set (DBCS) string if the locale is appropriate for DBCS.

cchSrc

Specifies the size, in bytes, of the string pointed to by the lpSrcStr parameter. If this count includes a null terminator, the function returns character type information for the null terminator. If this value is −1, the string is assumed to be null terminated and the length is calculated automatically.

lpCharType

Points to an array of 16-bit values. The length of this array must be large enough to receive one 16-bit value for each character in the source string. When the function returns, this array contains one word corresponding to each character in the source string.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

The lpSrcStr and lpCharType pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The Locale parameter is only used to perform string conversion to Unicode. It has nothing to do with the CTYPEs the function returns. The CTYPEs are solely determined by Unicode code points, and do not vary on a locale basis. For example, Greek letters are C1_ALPHA for any Locale value.

The character-type bits are divided into several levels. The information for one level can be retrieved by a single call to this function. Each level is limited to 16 bits of information so that the other mapping routines, which are limited to 16 bits of representation per character, can also return character-type information.

The character types supported by this function include the following.

Ctype 1

These types support ANSI C and POSIX (LC_CTYPE) character-typing functions. A combination of these values is returned in the array pointed to by the lpCharType parameter when the dwInfoType parameter is set to CT_CTYPE1.

Name	Value	Meaning
C1_UPPER	0x0001	Uppercase
C1_LOWER	0x0002	Lowercase
C1_DIGIT	0x0004	Decimal digits
C1_SPACE	0x0008	Space characters
C1_PUNCT	0x0010	Punctuation
C1_CNTRL	0x0020	Control characters
C1_BLANK	0x0040	Blank characters
C1_XDIGIT	0x0080	Hexadecimal digits
C1_ALPHA	0x0100	Any linguistic character: alphabetic, syllabary, or ideographic
The following character types are either constant or computable from basic types and do not need to be supported by this function.

Type	Description
Alphanumeric	Alphabetic characters and digits (C1_ALPHA and C1_DIGIT)
Printable	Graphic characters and blanks (all C1_* types except C1_CNTRL)
Ctype 2

These types support proper layout of Unicode text. The direction attributes are assigned so that the bidirectional layout algorithm standardized by Unicode produces accurate results. These types are mutually exclusive. For more information about the use of these attributes, see The Unicode Standard: Worldwide Character Encoding, Volumes 1 and 2, Addison Wesley Publishing Company: 1991, 1992, ISBN 0201567881.

Name	Value	Meaning
Strong:
C2_LEFTTORIGHT	0x1	Left to right
C2_RIGHTTOLEFT	0x2	Right to left
Weak:
C2_EUROPENUMBER	0x3	European number, European digit
C2_EUROPESEPARATOR	0x4	European numeric separator
C2_EUROPETERMINATOR	0x5	European numeric terminator
C2_ARABICNUMBER	0x6	Arabic number
C2_COMMONSEPARATOR	0x7	Common numeric separator
Neutral:
C2_BLOCKSEPARATOR	0x8	Block separator
C2_SEGMENTSEPARATOR	0x9	Segment separator
C2_WHITESPACE	0xA	White space
C2_OTHERNEUTRAL	0xB	Other neutrals
Not applicable:
C2_NOTAPPLICABLE	0x0	No implicit directionality (for example, control codes)
Ctype 3

These types are intended to be placeholders for extensions to the POSIX types required for general text processing or for the standard C library functions. These types are supported in the current version of Windows NT. A combination of these values is returned when dwInfoType is set to CT_CTYPE3.

Name	Value	Meaning
C3_NONSPACING	0x1	Nonspacing mark
C3_DIACRITIC	0x2	Diacritic nonspacing mark
C3_VOWELMARK	0x4	Vowel nonspacing mark
C3_SYMBOL	0x8	Symbol
C3_KATAKANA	0x10	Katakana character
C3_HIRAGANA	0x20	Hiragana character
C3_HALFWIDTH	0x40	Half-width character
C3_FULLWIDTH	0x80	Full-width character
C3_IDEOGRAPH	0x100	Ideographic character
C3_KASHIDA	0x200	Arabic Kashida character
C3_ALPHA	0x8000	All linguistic characters (alphabetic, syllabary, and ideographic)
Not applicable:
C3_NOTAPPLICABLE	0x0	Not applicable
See Also

GetLocaleInfo, GetStringTypeEx, GetStringTypeW


GetStringTypeEx

The GetStringTypeEx function returns character-type information for the characters in the specified source string. For each character in the string, the function sets one or more bits in the corresponding 16-bit element of the output array. Each bit identifies a given character type, such as whether the character is a letter, a digit, or neither.

Unlike its close relatives GetStringTypeA and GetStringTypeW, GetStringTypeEx exhibits appropriate A or W behavior through the use of the #define UNICODE switch. It is the recommended Win32 function.

BOOL GetStringTypeEx(

LCID  Locale,	// locale identifer
DWORD  dwInfoType,	// information-type options
LPCTSTR  lpSrcStr,	// address of source string
int  cchSrc,	// number of characters in string
LPWORD  lpCharType	// address of buffer for output
);
Parameters

Locale

Specifies the locale identifier. This value uniquely defines the ANSI code page to use to translate the string pointed to by lpSrcStr from ANSI to Unicode. The function then analyzes each Unicode character for character type information. Note that the W version of this function ignores this parameter.

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale
LOCALE_USER_DEFAULT	Default user locale
dwInfoType

Specifies the type of character information the user wants to retrieve. The various types are divided into different levels (see the following Remarks section for a list of the information included in each type). This parameter can specify one of the following character type flags:

CT_CTYPE1	Retrieve character type information.
CT_CTYPE2	Retrieve bidirectional layout information.
CT_CTYPE3	Retrieve text processing information.
lpSrcStr

Points to the string for which character types are requested. If cchSrc is −1, the string is assumed to be null terminated. This must be a Unicode string for the W version of this function, and an ANSI string for the A version. Note that for the A  version, this can be a double-byte character set (DBCS) string if the locale is appropriate for DBCS.

cchSrc

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the string pointed to by the lpSrcStr parameter. If this count includes a null terminator, the function returns character type information for the null terminator. If this value is −1, the string is assumed to be null terminated and the length is calculated automatically.

lpCharType

Points to an array of 16-bit values. The length of this array must be large enough to receive one 16-bit value for each character in the source string. When the function returns, this array contains one word corresponding to each character in the source string.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

The GetStringTypeEx function exists to circumvent a limitation caused by the difference in parameters of GetStringTypeA and GetStringTypeW. That parameter difference prevents an application from automatically invoking the proper A or W version of GetStringType* through the use of the #define UNICODE switch. GetStringTypeEx, on the other hand, behaves properly as regards that switch. Thus, it is the recommended Win32 function.

The Locale parameter is only used to perform string conversion to Unicode. It has nothing to do with the CTYPEs the function returns. The CTYPEs are solely determined by Unicode code points, and do not vary on a locale basis. For example, Greek letters are C1_ALPHA for any Locale value.

The lpSrcStr and lpCharType pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The character-type bits are divided into several levels. The information for one level can be retrieved by a single call to this function. Each level is limited to 16 bits of information so that the other mapping routines, which are limited to 16 bits of representation per character, can also return character-type information.

The character types supported by this function include the following.

Ctype 1

These types support ANSI C and POSIX (LC_CTYPE) character-typing functions. A combination of these values is returned in the array pointed to by the lpCharType parameter when the dwInfoType parameter is set to CT_CTYPE1.

Name	Value	Meaning
C1_UPPER	0x0001	Uppercase
C1_LOWER	0x0002	Lowercase
C1_DIGIT	0x0004	Decimal digits
C1_SPACE	0x0008	Space characters
C1_PUNCT	0x0010	Punctuation
C1_CNTRL	0x0020	Control characters
C1_BLANK	0x0040	Blank characters
C1_XDIGIT	0x0080	Hexadecimal digits
C1_ALPHA	0x0100	Any linguistic character: alphabetic, syllabary, or ideographic
The following character types are either constant or computable from basic types and do not need to be supported by this function.

Type	Description
Alphanumeric	Alphabetic characters and digits (C1_ALPHA and C1_DIGIT)
Printable	Graphic characters and blank (all C1_* types except C1_CNTRL)
Ctype 2

These types support proper layout of Unicode text. The direction attributes are assigned so that the bidirectional layout algorithm standardized by Unicode produces accurate results. These types are mutually exclusive. For more information about the use of these attributes, see The Unicode Standard: Worldwide Character Encoding, Volumes 1 and 2, Addison Wesley Publishing Company: 1991, 1992, ISBN 0201567881.

Name	Value	Meaning
Strong:
C2_LEFTTORIGHT	0x1	Left to right
C2_RIGHTTOLEFT	0x2	Right to left
Weak:
C2_EUROPENUMBER	0x3	European number, European digit
C2_EUROPESEPARATOR	0x4	European numeric separator
C2_EUROPETERMINATOR	0x5	European numeric terminator
C2_ARABICNUMBER	0x6	Arabic number
C2_COMMONSEPARATOR	0x7	Common numeric separator
Neutral:
C2_BLOCKSEPARATOR	0x8	Block separator
C2_SEGMENTSEPARATOR	0x9	Segment separator
C2_WHITESPACE	0xA	White space
C2_OTHERNEUTRAL	0xB	Other neutrals
Not applicable:
C2_NOTAPPLICABLE	0x0	No implicit directionality (for example, control codes)
Ctype 3

These types are intended to be placeholders for extensions to the POSIX types required for general text processing or for the standard C library functions. These types are supported in the current version of Windows NT. A combination of these values is returned when dwInfoType is set to CT_CTYPE3.

Name	Value	Meaning
C3_NONSPACING	0x1	Nonspacing mark
C3_DIACRITIC	0x2	Diacritic nonspacing mark
C3_VOWELMARK	0x4	Vowel nonspacing mark
C3_SYMBOL	0x8	Symbol
C3_KATAKANA	0x10	Katakana character
C3_HIRAGANA	0x20	Hiragana character
C3_HALFWIDTH	0x40	Half-width character
C3_FULLWIDTH	0x80	Full-width character
C3_IDEOGRAPH	0x100	Ideographic character
C3_KASHIDA	0x200	Arabic Kashida character
C3_ALPHA	0x8000	All linguistic characters (alphabetic, syllabary, and ideographic)
Not applicable:
C3_NOTAPPLICABLE	0x0	Not applicable
See Also

GetLocaleInfo, GetStringTypeA, GetStringTypeW


GetStringTypeW

The GetStringTypeW function returns character-type information for the characters in the specified source string. For each character in the string, the function sets one or more bits in the corresponding 16-bit element of the output array. Each bit identifies a given character type, such as whether the character is a letter, a digit, or neither.

BOOL GetStringTypeW(

DWORD  dwInfoType,	// information-type options
LPCWSTR  lpSrcStr,	// address of source string
int  cchSrc,	// number of characters in string
LPWORD  lpCharType	// address of buffer for output
);
Parameters

dwInfoType

Specifies the type of character information the user wants to retrieve. The various types are divided into different levels (see the following Remarks section for a list of the information included in each type). This parameter can specify one of the following character type flags:

CT_CTYPE1	Retrieve character type information.
CT_CTYPE2	Retrieve bidirectional layout information.
CT_CTYPE3	Retrieve text processing information.
lpSrcStr

Points to the string for which character types are requested. If cchSrc is −1, the string is assumed to be null terminated. This must be a Unicode string.

cchSrc

Specifies the size, in characters, of the string pointed to by the lpSrcStr parameter. If this count includes a null terminator, the function returns character type information for the null terminator. If this value is −1, the string is assumed to be null terminated and the length is calculated automatically.

lpCharType

Points to an array of 16-bit values. The length of this array must be large enough to receive one 16-bit value for the number of characters specified in the cchSrc parameter. When the function returns, this array contains one word corresponding to each Unicode character in the source string.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

Note that the GetStringTypeA function has one more parameter than the GetStringTypeW function: GetStringTypeA has a first parameter that is an LCID named Locale. This parameter does not exist in the GetStringTypeW function. Because of that parameter difference, an application cannot automatically invoke the proper A or W version of GetStringType* through the use of the #define UNICODE switch. An application can circumvent this limitation by using GetStringTypeEx; it is the recommended Win32 function.

The lpSrcStr and lpCharType pointers must not be the same. If they are the same, the function fails and GetLastError returns ERROR_INVALID_PARAMETER.

The character-type bits are divided into several levels. The information for one level can be retrieved by a single call to this function. Each level is limited to 16 bits of information so that the other mapping routines, which are limited to 16 bits of representation per character, can also return character-type information.

The character types supported by this function include the following.

Ctype 1

These types support ANSI C and POSIX (LC_CTYPE) character-typing functions. A combination of these values is returned in the array pointed to by the lpCharType parameter when the dwInfoType parameter is set to CT_CTYPE1.

Name	Value	Meaning
C1_UPPER	0x0001	Uppercase
C1_LOWER	0x0002	Lowercase
C1_DIGIT	0x0004	Decimal digits
C1_SPACE	0x0008	Space characters
C1_PUNCT	0x0010	Punctuation
C1_CNTRL	0x0020	Control characters
C1_BLANK	0x0040	Blank characters
C1_XDIGIT	0x0080	Hexadecimal digits
C1_ALPHA	0x0100	Any linguistic character: alphabetic, syllabary, or ideographic
The following character types are either constant or computable from basic types and do not need to be supported by this function.

Type	Description
Alphanumeric	Alphabetic characters and digits (C1_ALPHA and C1_DIGIT)
Printable	Graphic characters and blanks (all C1_* types except C1_CNTRL)
Ctype 2

These types support proper layout of Unicode text. The direction attributes are assigned so that the bidirectional layout algorithm standardized by Unicode produces accurate results. These types are mutually exclusive. For more information about the use of these attributes, see The Unicode Standard: Worldwide Character Encoding, Volumes 1 and 2, Addison Wesley Publishing Company: 1991, 1992, ISBN 0201567881.

Name	Value	Meaning
Strong:
C2_LEFTTORIGHT	0x1	Left to right
C2_RIGHTTOLEFT	0x2	Right to left
Weak:
C2_EUROPENUMBER	0x3	European number, European digit
C2_EUROPESEPARATOR	0x4	European numeric separator
C2_EUROPETERMINATOR	0x5	European numeric terminator
C2_ARABICNUMBER	0x6	Arabic number
C2_COMMONSEPARATOR	0x7	Common numeric separator
Neutral:
C2_BLOCKSEPARATOR	0x8	Block separator
C2_SEGMENTSEPARATOR	0x9	Segment separator
C2_WHITESPACE	0xA	White space
C2_OTHERNEUTRAL	0xB	Other neutrals
Not applicable:
C2_NOTAPPLICABLE	0x0	No implicit directionality (for example, control codes)
Ctype 3

These types are intended to be placeholders for extensions to the POSIX types required for general text processing or for the standard C library functions. These types are supported in the current version of Windows NT. A combination of these values is returned when dwInfoType is set to CT_CTYPE3.

Name	Value	Meaning
C3_NONSPACING	0x1	Nonspacing mark
C3_DIACRITIC	0x2	Diacritic nonspacing mark
C3_VOWELMARK	0x4	Vowel nonspacing mark
C3_SYMBOL	0x8	Symbol
C3_KATAKANA	0x10	Katakana character
C3_HIRAGANA	0x20	Hiragana character
C3_HALFWIDTH	0x40	Half-width character
C3_FULLWIDTH	0x80	Full-width character
C3_IDEOGRAPH	0x100	Ideographic character
C3_KASHIDA	0x200	Arabic Kashida character
C3_ALPHA	0x8000	All linguistic characters (alphabetic, syllabary, and ideographic)
Not applicable:
C3_NOTAPPLICABLE	0x0	Not applicable
See Also

GetLocaleInfo, GetStringTypeA, GetStringTypeEx


GetSubMenu

The GetSubMenu function retrieves the handle of the pop-up menu activated by the specified menu item.

HMENU GetSubMenu(

HMENU  hMenu,	// handle of menu
int  nPos	// menu item position
);
Parameters

hMenu

Identifies the menu.

nPos

Specifies the zero-based relative position in the given menu of an item that activates a pop-up menu.

Return Value

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

The GetSysColor function retrieves the current color of the specified display element. Display elements are the parts of a window and the Windows display that appear on the system display screen.

DWORD GetSysColor(

int  nIndex	// display element
);
Parameters

nIndex

Specifies the display element whose color is to be retrieved. This parameter must be one of the following values:

Value	Meaning
COLOR_3DDKSHADOW	Windows 95 only: Dark shadow for three-dimensional display elements.
COLOR_3DFACE	Windows 95 only: Face color for three-dimensional display elements.
COLOR_3DHILIGHT	Windows 95 only: Highlight color for three-dimensional display elements (for edges facing the light source.)
COLOR_3DLIGHT	Windows 95 only: Light color for three-dimensional display elements (for edges facing the light source.)
COLOR_3DSHADOW	Windows 95 only: Shadow color for three-dimensional display elements (for edges facing away from the light source).
COLOR_ACTIVEBORDER	Active window border.
COLOR_ACTIVECAPTION	Active window caption.
COLOR_APPWORKSPACE	Background color of multiple document interface (MDI) applications.
COLOR_BACKGROUND	Desktop.
COLOR_BTNFACE	Windows NT only: Face shading on push buttons.
COLOR_BTNHILIGHT	Windows 95 only: Highlight color  for buttons (same as COLOR_3DHILIGHT).
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_INFOBK	Windows 95 only: Background color for tooltip controls.
COLOR_INFOTEXT	Windows 95 only: Text color for tooltip controls.
COLOR_MENU	Menu background.
COLOR_MENUTEXT	Windows NT only: Text in menus.
COLOR_SCROLLBAR	Scroll bar gray area.
COLOR_WINDOW	Window background.
COLOR_WINDOWFRAME	Window frame.
COLOR_WINDOWTEXT	Text in windows.
Return Value

If the function succeeds, the return value is the red, green, blue (RGB) color value that specifies the color of the given element.

Remarks

System colors for monochrome displays are usually interpreted as shades of gray.

See Also

SetSysColors


GetSysColorBrush  (preliminaryWindows 95)
GetSysColorBrush  (preliminary−Windows 95)

The GetSysColorBrush function retrieves a handle identifying a logical brush that corresponds to the specified color index.

HBRUSH GetSysColorBrush(

int  nIndex	// system color index
);
Parameters

nIndex

Specifies a color index. This value corresponds to the color used to paint one of the 21 window elements.

Return Value

If the function succeeds, the return value identifies a logical brush. To get extended error information, call GetLastError.

Remarks

A brush is a bitmap that Windows uses to paint the interiors of filled shapes. An application can retrieve the current system colors by calling the GetSysColor function. An application can set the current system colors by calling the SetSysColors function.

An application must not register a window class for a window using a system brush.

See Also

GetSysColor, SetSysColors


GetSysModalWindow

The GetSysModalWindow function is not implemented in the Win32 API.


GetSystemDefaultLangID

The GetSystemDefaultLangID function retrieves the system default language identifier.

LANGID GetSystemDefaultLangID(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the system default language identifier.

See Also

GetUserDefaultLangID, MAKELANGID


GetSystemDefaultLCID

The GetSystemDefaultLCID function retrieves the system default locale identifier.

LCID GetSystemDefaultLCID(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the system default locale identifier.

See Also

GetLocaleInfo, GetUserDefaultLCID, MAKELCID


GetSystemDir

The GetSystemDir function is not supported in the Win32 API. For Win32-based applications, use the GetSystemDirectory function to determine the system directory.


GetSystemDirectory

The GetSystemDirectory function retrieves the path of the Windows system directory. The system directory contains such files as Windows libraries, drivers, and font files.

UINT GetSystemDirectory(

LPTSTR  lpBuffer,	// address of buffer for system directory
UINT  uSize	// size of directory buffer
);
Parameters

lpBuffer

Points to the buffer to receive the null-terminated string containing the path. This path does not end with a backslash unless the system directory is the root directory. For example, if the system directory is named WINDOWS\SYSTEM on drive C, the path of the system directory retrieved by this function is C:\WINDOWS\SYSTEM.

uSize

Specifies the maximum size of the buffer, in characters. This value should be set to at least MAX_PATH.

Return Value

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer, not including the terminating null character. If the length is greater than the size of the buffer, the return value is the size of the buffer required to hold the path.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Applications should not create files in the system directory. If the user is running a shared version of Windows, the application does not have write access to the system directory. Applications should create files only in the directory returned by the GetWindowsDirectory function.

See Also

GetCurrentDirectory, GetWindowsDirectory, SetCurrentDirectory


GetSystemInfo

The GetSystemInfo function returns information about the current system.

VOID GetSystemInfo(

LPSYSTEM_INFO  lpSystemInfo	// address of system information structure
);
Parameters

lpSystemInfo

Points to a SYSTEM_INFO structure to be filled in by this function.

Return Value

This function does not return a value.

See Also

SYSTEM_INFO


GetSystemMenu

The GetSystemMenu function allows the application to access the System menu (also known as the Control menu) for copying and modifying.

HMENU GetSystemMenu(

HWND  hWnd,	// handle of window to own System menu
BOOL  bRevert	// reset flag
);
Parameters

hWnd

Identifies the window that will own a copy of the System menu.

bRevert

Specifies the action to be taken. If this parameter is FALSE, GetSystemMenu 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.

Return Value

If the bRevert parameter is FALSE, the return value is the handle of a copy of the System menu. If the bRevert parameter is TRUE, the return value is NULL.

Remarks

Any window that does not use the GetSystemMenu menu to make its own copy of the System menu receives the standard 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 perform its own checking or graying by responding to the WM_INITMENU message that is sent before any menu is displayed.

See Also

GetMenu, WM_INITMENU, WM_SYSCOMMAND


GetSystemMetrics

The GetSystemMetrics function retrieves various system metrics and system configuration settings.

System metrics are the dimensions (widths and heights) of Windows display elements. All dimensions retrieved by GetSystemMetrics are in pixels.

int GetSystemMetrics(

int  nIndex	// system metric or configuration setting to retrieve
);
Parameters

nIndex

Specifies the system metric or configuration setting to retrieve. All SM_CX* values are widths. All SM_CY* values are heights. The following values are defined:

Value	Meaning
SM_ARRANGE	Windows 95 only: Flags specifying how the system arranged minimized windows. For more information about minimized windows, see the following Remarks section.
SM_CLEANBOOT	Windows 95 only: Value that specifies how the system was started: 0 Normal boot 1 Fail-safe boot 2 Fail-safe with network boot Fail-safe boot (also called SafeBoot) bypasses the user's startup files.
SM_CMETRICS	Windows 95 only: Number of system metrics and flags.
SM_CMOUSEBUTTONS	Number of buttons on mouse, or zero if no mouse is installed.
SM_CXBORDER,  SM_CYBORDER	Windows NT only: Width and height of window border.  Windows 95 only: Dimensions of a single border, in pixels.
SM_CXCURSOR,  SM_CYCURSOR	Windows NT only: Width and height of cursor. Windows 95 only: Dimensions of standard cursor bitmaps, in pixels.
SM_CXDLGFRAME, SM_CYDLGFRAME	Width and height of window frame for a window that has the WS_DLGFRAME style.  Windows 95 only: Obsolete; use SM_CX_FIXEDFRAME and SM_CYFIXEDFRAME instead.
SM_CXDOUBLECLK,  SM_CYDOUBLECLK	Windows NT only: Width and height of a rectangle around the location of a first click in a double-click sequence. The second click must occur within this rectangle for the system to consider the two clicks a double-click. Windows 95 only: Dimensions, in pixels, of the rectangle within which two successive mouse clicks must fall to generate a double-click. (The two clicks must also occur within a specified time.)
SM_CXFRAME, SM_CYFRAME	Width and height of window frame for a window that can be resized.  Windows 95 only: Obsolete; use SM_CX_FIXEDFRAME and SM_CYFIXEDFRAME instead.
SM_CXFULLSCREEN, SM_CYFULLSCREEN	Width and height of the client area for a full-screen window.
SM_CXHSCROLL,  SM_CYHSCROLL	Width and height of arrow bitmap on horizontal scrollbar.
SM_CXHTHUMB,	Width of horizontal scrollbar thumb box.
SM_CXICON,  SM_CYICON	Width and height of an icon.
SM_CXICONSPACING, SM_CYICONSPACING	Windows NT only: Width and height of rectangular cell that Program Manager uses to position tiled icons. Windows 95 only: Dimensions of a grid cell for items in large icon view, in pixels. Each item fits into a rectangle of this size when arranged. These values are always greater than or equal to SM_CXICON and SM_CYICON.
SM_CXMAXIMIZED, SM_CYMAXIMIZED	Windows 95 only: Default dimensions of a maximized top-level window, in pixels.
SM_CXMAXTRACK, SM_CYMAXTRACK	Windows 95 only: Default maximum dimensions of a window that has a caption and sizing borders. The user cannot drag the window frame to a size larger than these dimensions. A window can override these values by processing the WM_GETMINMAXINFO message.
SM_CXMENUCHECK, SM_CYMENUCHECK	Windows 95 only: Dimensions of the default menu check-mark bitmap, in pixels.
SM_CXMENUSIZE, SM_CYMENUSIZE	Windows 95 only: Dimensions of menu bar buttons (such as multiple document (MIDI) child close), in pixels.
SM_CXMINIMIZED, SM_CYMINIMIZED	Windows 95 only: Dimensions of a normal minimized window, in pixels.
SM_CXMINSPACING SM_CYMINSPACING	Windows 95 only: Dimensions of a grid cell for minimized windows, in pixels. Each minimized window fits into a rectangle this size when arranged. These values are always greater than or equal to SM_CXMINIMIZED and SM_CYMINIMIZED.
SM_CXMINTRACK, SM_CYMINTRACK	Minimum tracking width and height of a window. The user cannot drag the window frame to a size smaller than these dimensions. A window can override these values by processing the WM_GETMINMAXINFO message.
SM_CXSCREEN,  SM_CYSCREEN	Width and height of the screen.
SM_CXSIZE,  SM_CYSIZE	Windows NT only: Width and height of bitmaps contained in title bar. Windows 95 only: Dimensions of caption buttons, in pixels.
SM_CXSIZEFRAME, SM_CYSIXEFRAME	Windows 95 only: Dimensions, in pixels, of the window frame for a window that has the WS_THICKFRAME style. Formerly SM_CXFRAME and SM_CYFRAME.
SM_CXSMICON, SM_CYSICON	Windows 95 only: Recommended dimensions of a small icon, in pixels. Small icons typically appear in window captions and in small icon view.
SM_CXSMSIZE SM_CYSMSIZE	Windows 95 only: Dimensions of small caption buttons, in pixels.
SM_CXVSCROLL SM_CYHSCROLL	Windows 95 only: Width of vertical scrollbar and height of horizontal scrollbar, in pixels.
SM_CXHSCROLL SM_CYVSCROLL	Windows 95 only: Width of the arrow bitmap on a horizontal scrollbar, and height of the arrow bitmap on a vertical scrollbar.
SM_CXVSCROLL,  SM_CYVSCROLL	Windows NT only: Width and height of arrow bitmap on vertical scrollbar.
SM_CYVTHUMB	Height of vertical scrollbar thumb.
SM_CYCAPTION	Height of normal caption area.
SM_CYKANJIWINDOW	For double-byte character set versions of Windows, height of the Kanji window at the bottom of the screen.
SM_CYMENU	Height of single-line menu bar.
SM_CYSMCAPTION	Windows 95 only: Height of a small caption, in pixels.
SM_DBCSENABLED	TRUE or non-zero if the double-byte character set (DBCS) version of USER.EXE is installed; FALSE, or zero otherwise.
SM_DEBUG	TRUE or non-zero if the debugging version of USER.EXE is installed; FALSE, or zero, otherwise.
SM_MENUDROPALIGNMENT	TRUE, or non-zero if pop-up menus are right-aligned relative to the corresponding menu-bar item; FALSE, or zero if they are left-aligned.
SM_MIDEASTENABLED	Windows 95 only: TRUE if the system is enabled for Hebrew/Arabic languages.
SM_MOUSEPRESENT	TRUE or non-zero if a mouse is installed; FALSE, or zero, otherwise.
SM_NETWORK	Windows 95 only: The least significant bit is set if a network is present; otherwise, it is cleared. The other bits are reserved for future use.
SM_PENWINDOWS	TRUE or non-zero if the Microsoft Windows for Pen computing extensions are installed; zero, or FALSE, otherwise.
SM_SECURE	Windows 95 only: TRUE if security is present, FALSE otherwise.
SM_SHOWSOUNDS	TRUE or non-zero if the user requires an application to present information visually in situations where it would otherwise present the information only in audible form; FALSE, or zero, otherwise.
SM_SLOWMACHINE	Windows 95 only: TRUE if the computer has a low-end (slow) processor, FALSE otherwise.
SM_SWAPBUTTON	TRUE or non-zero if the meanings of the left and right mouse buttons are swapped; FALSE, or zero, otherwise.
Return Value

The return value is the requested system metric or configuration setting.

Remarks

System metrics may vary from display to display.

The SM_ARRANGE setting specifies how the system arranges minimized windows, and consists of a starting position and a direction. The starting position can be one of these values:

Value	Meaning
ARW_BOTTOMLEFT	Start at lower-left corner of screen (default position).
ARW_BOTTOMRIGHT	Start at lower-right corner of screen. Equivelant to ARW_STARTRIGHT.
ARW_HIDE	Hide minimized windows by moving them off of the visible area of the screen.
ARW_TOPLEFT	Start at upper-left corner of screen. Equivelant to ARV_STARTTOP.
ARW_TOPRIGHT	Start at upper-right corner of screen. Equivelant to ARW_STARTTOP | SRW_STARTRIGHT.

The direction in which to arrange can be one of these values:

Value	Meaning
ARW_DOWN	Arrange vertically, top to bottom.
ARW_LEFT	Arrange horizontally, left to right.
ARW_RIGHT	Arrange horizontally, right to left.
ARW_UP	Arrange vertically, bottom to top.


GetSystemPaletteEntries

The GetSystemPaletteEntries function retrieves a range of palette entries from the system palette that is associated with the specified device context.

UINT GetSystemPaletteEntries(

HDC  hdc,	// handle of device context
UINT  iStartIndex,	// index of first entry to be retrieved
UINT  nEntries,	// number of entries to be retrieved
LPPALETTEENTRY  lppe	// array receiving system-palette entries
);
Parameters

hdc

Identifies the device context.

iStartIndex

Specifies the first entry to be retrieved from the system palette.

nEntries

Specifies the number of entries to be retrieved from the system palette.

lppe

Points to an array of PALETTEENTRY structures to receive the palette entries. The array must contain at least as many structures as specified by the nEntries parameter. If this parameter is NULL, the function returns the total number of entries in the palette.

Return Value

If the function succeeds, the return value is the number of entries retrieved from the palette.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

See Also

GetDeviceCaps, GetPaletteEntries, PALETTEENTRY


GetSystemPaletteUse

The GetSystemPaletteUse function retrieves the current state of the system (physical) palette for the specified device context.

UINT GetSystemPaletteUse(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value is the current state of the system palette. It can be any of the following values:

Value	Meaning
SYSPAL_NOSTATIC	The system palette contains no static colors except black and white.
SYSPAL_STATIC	The system palette contains static colors that will not change when an application realizes its logical palette.
SYSPAL_ERROR	The given device context is invalid or does not support a color palette.
To get extended error information, call GetLastError.

Remarks

By default, the system palette contains 20 static colors that are not changed when an application realizes its logical palette. An application can gain access to most of these colors by calling the SetSystemPaletteUse function.

The device context identified by the hdc parameter must represent a device that supports color palettes.

An application can determine whether or not a device supports color palettes by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

See Also

GetDeviceCaps, SetSystemPaletteUse


GetSystemPowerStatus  (preliminaryWindows 95)
GetSystemPowerStatus  (preliminary−Windows 95)

The GetSystemPowerStatus function retrieves the power status of the system. The status indicates whether the system is running on AC or DC power, whether the battery is currently charging, and how much battery life currently remains.

BOOL GetSystemPowerStatus(

LPSYSTEM_POWER_STATUS  lpSystemPowerStatus
);
Parameters

lpSystemPowerStatus

Pointer to a SYSTEM_POWER_STATUS structure that receives status information.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

SYSTEM_POWER_STATUS


GetSystemTime

The GetSystemTime function retrieves the current system date and time. The system time is expressed in Coordinated Universal Time (UTC).

VOID GetSystemTime(

LPSYSTEMTIME  lpSystemTime	// address of system time structure
);
Parameters

lpSystemTime

Points to a SYSTEMTIME structure to receive the current system date and time.

Return Value

This function does not return a value.

See Also

GetLocalTime, GetSystemTimeAdjustment, SetSystemTime, SYSTEMTIME


GetSystemTimeAdjustment

The GetSystemTimeAdjustment function determines whether the system is applying periodic time adjustments to its time-of-day clock at each clock interrupt, along with the value and period of any such adjustments. Note that the period of such adjustments is equivalent to the time period between clock interrupts.

BOOL GetSystemTimeAdjustment(

PDWORD  lpTimeAdjustment,	// size, in 100-nanosecond units, of a periodic time adjustment
PDWORD  lpTimeIncrement,	// time, in 100-nanosecond units, between periodic time adjustments
PBOOL  lpTimeAdjustmentDisabled	// whether periodic time adjustment is disabled or enabled
);
Parameters

lpTimeAdjustment

Pointer to a DWORD that the function sets to the number of 100-nanosecond units added to the time-of-day clock at each periodic time adjustment.

lpTimeIncrement

Pointer to a DWORD that the function sets to the interval, counted in 100-nanosecond units, between periodic time adjustments. This interval is the time period between a system's clock interrupts.

lpTimeAdjustmentDisabled

Pointer to a BOOL that the function sets to indicate whether periodic time adjustment is in effect.

A value of TRUE indicates that periodic time adjustment is disabled. At each clock interrupt, the system merely adds the interval between clock interrupts to the time-of-day clock. The system is free, however, to adjust its time-of-day clock using other techniques. Such other techniques may cause the time-of-day clock to noticeably jump when adjustments are made.

A value of FALSE indicates that periodic time adjustment is being used to adjust the time-of-day clock. At each clock interrupt, the system adds the time increment specified by SetSystemTimeAdjustment's dwTimeIncrement parameter to the time-of-day clock. The system will not interfere with the time adjustment scheme, and will not attempt to synchronize time of day on its own via other techniques.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The GetSystemTimeAdjustment and SetSystemTimeAdjustment functions support algorithms that want to synchronize the time-of-day clock, reported by GetSystemTime and GetLocalTime, with another time source using a periodic time adjustment applied at each clock interrupt.

When periodic time adjustment is in effect, the system adds an adjusting value to the time-of-day clock at a periodic interval, at each clock interrupt. The GetSystemTimeAdjustment function lets a caller determine whether periodic time adjustment is enabled, and if it is, obtain the amount of each adjustment and the time between adjustments. The SetSystemTimeAdjustment function lets a caller enable or disable periodic time adjustment, and set the value of the adjusting increment.

See Also

SetSystemTimeAdjustment, GetSystemTime, GetLocalTime


GetTabbedTextExtent

The GetTabbedTextExtent function computes the width and height of a character string. If the string contains one or more tab characters, the width of the string is based upon the specified tab stops. The GetTabbedTextExtent function uses the currently selected font to compute the dimensions of the string.

DWORD GetTabbedTextExtent(

HDC  hDC,	// handle of device context
LPCTSTR  lpString,	// address of character string
int  nCount,	// number of characters in string
int  nTabPositions,	// number of tab positions
LPINT  lpnTabStopPositions	// address of array of tab positions
);
Parameters

hDC

Identifies the device context.

lpString

Points to a character string.

nCount

Specifies the number of characters in the text string.

nTabPositions

Specifies the number of tab-stop positions in the array pointed to by the lpnTabStopPositions parameter.

lpnTabStopPositions

Points to an array containing the tab-stop positions, in device units. The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array.

Return Value

If the function succeeds, the return value is the dimensions of the string. The height is in the high-order word and the width is in the low-order word.

If the function fails, the return value is 0. GetTabbedTextExtent will fail if hDC is invalid and if nTabPositions is less than 0.

Remarks

The current clipping region does not affect the width and height returned by the GetTabbedTextExtent function.

Because some devices do not place characters in regular cell arrays (that is, they kern the characters), the sum of the extents of the characters in a string may not be equal to the extent of the string.

If the nTabPositions parameter is zero and the lpnTabStopPositions parameter is NULL, tabs are expanded to eight times the average character width.

If nTabPositions is 1, the tab stops are separated by the distance specified by the first value in the array to which lpnTabStopPositions points.

See Also

GetTextExtent, HIWORD, LOWORD, TabbedTextOut


GetTapeParameters

The GetTapeParameters function retrieves information that describes the tape or the tape drive.

DWORD GetTapeParameters(

HANDLE  hDevice,	// handle of open device
DWORD  dwOperation,	// type of information requested
LPDWORD  lpdwSize,	// address of returned information
LPVOID  lpTapeInformation	// tape media or drive information
);
Parameters

hDevice

Identifies the device about which information is sought. This handle is created by using the CreateFile function.

dwOperation

Specifies the type of information requested. This parameter must be one of the following values:

Value	Description
GET_TAPE_MEDIA_INFORMATION	Retrieves information about the tape in the tape device.
GET_TAPE_DRIVE_INFORMATION	Retrieves information about the tape device.
lpdwSize

Points to a variable that receives the size, in bytes, of the buffer specified by the lpTapeInformation parameter. If the buffer is too small, this parameter receives the required size.

lpTapeInformation

Points to a structure that contains the requested information. If the dwOperation parameter is GET_TAPE_MEDIA_INFORMATION, lpTapeInformation points to a TAPE_GET_MEDIA_PARAMETERS structure.

If dwOperation is GET_TAPE_DRIVE_INFORMATION, lpTapeInformation points to a TAPE_GET_DRIVE_PARAMETERS structure.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes:

Error code	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

The block size range values (maximum and minimum) returned by the GetTapeParameters function called with the dwOperation parameter set to the GET_TAPE_DRIVE_INFORMATION value will indicate system limits, not drive limits. However, it is the tape drive device and the media present in the drive that determine the true block size limits. Thus, an application may not be able to set all the block sizes mentioned in the range obtained by specifying GET_TAPE_DRIVE_INFORMATION in dwOperation.

See Also

CreateFile, SetTapeParameters, TAPE_GET_DRIVE_PARAMETERS, TAPE_GET_MEDIA_PARAMETERS


GetTapePosition

The GetTapePosition function retrieves the current address of the tape, in logical or absolute blocks.

DWORD GetTapePosition(

HANDLE  hDevice,	// handle of open device
DWORD  dwPositionType,	// type of address to obtain
LPDWORD  lpdwPartition,	// address of current tape partition
LPDWORD  lpdwOffsetLow,	// address of low-order 32 bits of tape position
LPDWORD  lpdwOffsetHigh	// address of high-order 32 bits of tape position
);
Parameters

hDevice

Identifies the device on which to get the tape position. This handle is created by using CreateFile.

dwPositionType

Specifies the type of address to obtain. This parameter can be one of the following values:

Value	Description
TAPE_ABSOLUTE_POSITION	The lpdwOffsetLow and lpdwOffsetHigh parameters receive the device-specific block address. The dwPartition parameter receives zero.
TAPE_LOGICAL_POSITION	The lpdwOffsetLow and lpdwOffsetHigh parameters receive the logical block address. The dwPartition parameter receives the logical tape partition.
lpdwPartition

Points to a variable that receives the number of the current tape partition. Partitions are numbered logically from 1 through n, where 1 is the first partition on the tape and n is the last. When a device-specific block address is retrieved, or if the device supports only one partition, this parameter receives zero.

lpdwOffsetLow

Points to a variable that receives the low-order 32 bits of the current tape position.

lpdwOffsetHigh

Points to a variable that receives the high-order 32 bits of the current tape position. This parameter can be NULL if the high-order 32 bits are not required.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes:

Error code	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

A logical block address is relative to a partition. The first logical block address on each partition is zero.

Call the GetTapeParameters function to obtain information about the status, capabilities, and capacities of tape drives and media.

See Also

CreateFile, GetTapeParameters, SetTapePosition


GetTapeStatus

The GetTapeStatus function indicates whether the tape device is ready to process tape commands.

DWORD GetTapeStatus(

HANDLE  hDevice	// handle of open device
);
Parameters

hDevice

Identifies the device for which to get the device status. This handle is created by using the CreateFile function.

Return Value

If the tape device is ready to accept appropriate tape-access commands without returning errors, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes:

Error code	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
See Also

CreateFile


GetTempDrive

The GetTempDrive function is not implemented in the Win32 API. Win32-based applications should use the GetTempPath function.


GetTempFileName

The GetTempFileName function creates a temporary filename of the following form: path\preuuuu.tmp.

The following table describes the filename syntax:

Component	Meaning
path	Path specified by the lpPathName parameter
pre	First three letters of the lpPrefixString string
uuuu	Hexadecimal value of uUnique
UINT GetTempFileName(

LPCTSTR  lpPathName,	// address of name of directory where temp. file is created
LPCTSTR  lpPrefixString,	// address of prefix of temp. filename
UINT  uUnique,	// number used to create temp. filename
LPTSTR  lpTempFileName	// address of buffer that will receive temp. filename
);
Parameters

lpPathName

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.

lpPrefixString

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.

lpTempFileName

Points to the buffer that receives the temporary filename. This null-terminated string consists of characters in the ANSI character set. This buffer should be at least the length, in bytes, specified by MAX_PATH to accommodate the path.

Return Value

The return value specifies a unique numeric value used in the temporary filename. If the uUnique parameter is nonzero, the return value specifies that same number.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

When Windows shuts down, temporary files whose names have been created by this function are not automatically deleted.

To avoid problems resulting from converting an ANSI character set string to a Windows string, an application should call the CreateFile function to create a temporary file.

If the uUnique parameter is zero, GetTempFileName attempts to form a unique number based on the current system time. If a file with the resulting filename exists, the number is increased by one and the test for existence is repeated. Testing continues until a unique filename is found. GetTempFileName then creates a file by that name and closes it. When uUnique is nonzero, no attempt is made to create and open the file.

See Also

CreateFile, GetTempPath


GetTempPath

The GetTempPath function retrieves the path of the directory designated for temporary files.  This function supersedes the GetTempDrive function.

DWORD GetTempPath(

DWORD  nBufferLength,	// size, in characters, of the buffer
LPTSTR  lpBuffer	// address of buffer for temp. path
);
Parameters

nBufferLength

Specifies the size, in characters, of the string buffer identified by lpBuffer.

lpBuffer

Points to a string buffer that receives the null-terminated string specifying the temporary file path.

Return Value

If the function succeeds, the return value is the length, in characters, of the string copied to lpBuffer, not including the terminating null character. If the return value is greater than nBufferLength, the return value is the size of the buffer required to hold the path.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

GetTempFileName


GetTextAlign

The GetTextAlign function retrieves the text-alignment setting for the specified device context.

UINT GetTextAlign(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value is the status of the text-alignment flags.

If the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

For a list of status return values, see the Remarks section. The return value is a combination of one or more of the following values:

Value	Meaning
TA_BASELINE	The reference point is on the base line of the text.
TA_BOTTOM	The reference point is on the bottom edge of the bounding rectangle.
TA_TOP	The reference point is on the top edge of the bounding rectangle.
TA_CENTER	The reference point is aligned horizontally with the center of the bounding rectangle.
TA_LEFT	The reference point is on the left edge of the bounding rectangle.
TA_RIGHT	The reference point is on the right edge of the bounding rectangle.
TA_RTLREADING	Windows 95 only: The text is laid out in right to left reading order, as opposed to the default left to right order. This only applies when the font selected into the device context is either Hebrew or Arabic.
TA_NOUPDATECP	The current position is not updated after each text output call.
TA_UPDATECP	The current position is updated after each text output call.
When the current font has a vertical default base line (as with Kanji), the following values are used instead of TA_BASELINE and TA_CENTER:

Value	Meaning
VTA_BASELINE	The reference point is on the base line of the text.
VTA_CENTER	The reference point is aligned vertically with the center of the bounding rectangle.
Remarks

The bounding rectangle is a rectangle bounding all of the character cells in a string of text. Its dimensions can be obtained by calling the 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, GetTextExtent, SetTextAlign, TextOut


GetTextCharacterExtra

The GetTextCharacterExtra function retrieves the current intercharacter spacing for the specified device context.

int GetTextCharacterExtra(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value is the current intercharacter spacing.

If the function fails, the return value is 0x8000000.

Remarks

The intercharacter spacing defines the extra space, in logical units along the base line, that the TextOut or ExtTextOut functions add to each character as a line is written. The spacing is used to expand lines of text.

See Also

ExtTextOut, SetTextCharacterExtra, TextOut


GetTextCharsetInfo  (preliminaryWindows 95)
GetTextCharsetInfo  (preliminary−Windows 95)

The GetTextCharsetInfo function retrieves information about the character set for the currently selected font.

UINT GetTextCharsetInfo(

HDC hdc,	// handle of device context
LPFONTSIGNATURE * lpSig,	// address of buffer for font-signature data
DWORD dwFlags	// reserved; must be zero
);
Parameters

hdc

Identifies the device context.

lpSig

Points to the buffer that receives the font signature block. The block includes both the Unicode and ANSI sections. This parameter can be NULL if the block is not required. If the font is not a TrueType font, the function sets the font signature to all zeros. In this case, use TranslateCharsetInfo to retrieve the generic signatures for character sets if required.

dwFlags

Reserved; must be zero.

Return Value

If the function succeeds, the return value is the character set of the currently selected font for the given device context.


GetTextColor

The GetTextColor function retrieves the current text color for the specified device context.

COLORREF GetTextColor(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value is the current text color as a COLORREF value.

If the function fails, the return value is CLR_INVALID.

Remarks

The text color defines the foreground color of characters drawn by using the TextOut or ExtTextOut function.

See Also

ExtTextOut, TextOut


GetTextExtent

The GetTextExtent function is not implemented in the Win32 API. This function is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the GetTextExtentPoint32 function.


GetTextExtentExPoint

The GetTextExtentExPoint function retrieves the number of characters in a specified string that will fit within a specified space and fills an array with the text extent for each of those characters. (A text extent is the distance between the beginning of the space and a character that will fit in the space.) This information is useful for word-wrapping calculations.

BOOL GetTextExtentExPoint(

HDC  hdc,	// handle of device context
LPCTSTR  lpszStr,	// address of character string
int  cchString,	// number of characters in string
int  nMaxExtent,	// maximum width for formatted string
LPINT  lpnFit,	// address of value specifying max. number of chars.
LPINT  alpDx,	// address of array for partial string widths
LPSIZE  lpSize	// address of structure with string dimensions
);
Parameters

hdc

Identifies the device context.

lpszStr

Points to the null-terminated string for which extents are to be retrieved.

cchString

Specifies the number of bytes in the string pointed to by the lpszStr parameter.

nMaxExtent

Specifies the maximum allowable width, in logical units, of the formatted string.

lpnFit

Points to an integer to receive a count of the maximum number of characters that will fit in the space specified by the nMaxExtent parameter. When the lpnFit parameter is NULL, the nMaxExtent parameter is ignored.

alpDx

Points to an array of integers to receive partial string extents. Each element in the array gives the distance, in logical units, between the beginning of the string and one of the characters that fits in the space specified by the nMaxExtent parameter. Although this array should have at least as many elements as characters specified by the cchString parameter, the function fills the array with extents only for as many characters as are given by the lpnFit parameter. If alpDx is NULL, the function does not compute partial string widths.

lpSize

Points to a SIZE structure that contains the dimensions of the string, in logical units when the function returns. This value cannot be NULL.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If both the lpnFit and alpDx parameters are NULL, calling the GetTextExtentExPoint function is equivalent to calling the GetTextExtentPoint function.

See Also

GetTextExtentPoint, SIZE


GetTextExtentPoint

The GetTextExtentPoint function computes the width and height of the specified string of text.

GetTextExtentPoint is provided for compatibility with 16-bit versions of Windows. Win32-based applications should call the GetTextExtentPoint32 function, which provides more accurate results.

BOOL GetTextExtentPoint(

HDC  hdc,	// handle of device context
LPCTSTR  lpString,	// address of text string
int  cbString,	// number of characters in string
LPSIZE  lpSize	// address of structure for string size
);
Parameters

hdc

Identifies the device context.

lpString

Points to the string of text. The string does not need to be zero-terminated, since cbString specifies the length of the string.

cbString

Specifies the number of characters in the string.

lpSize

Points to a SIZE structure in which the dimensions of the string are to be returned.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The GetTextExtentPoint function uses the currently selected font to compute the dimensions of the string. The width and height, in logical units, are computed without considering any clipping.

Because some devices kern characters, the sum of the extents of the characters in a string may not be equal to the extent of the string.

The calculated string width takes into account the intercharacter spacing set by the SetTextCharacterExtra function.

See Also

GetTextExtentPoint32, SetTextCharacterExtra, SIZE


GetTextExtentPoint32

The GetTextExtentPoint32 function computes the width and height of the specified string of text. This function supersedes the GetTextExtentPoint function.

BOOL GetTextExtentPoint32(

HDC  hdc,	// handle of device context
LPCTSTR  lpString,	// address of text string
int  cbString,	// number of characters in string
LPSIZE  lpSize	// address of structure for string size
);
Parameters

hdc

Identifies the device context.

lpString

Points to the string of text. The string does not need to be zero-terminated, since cbString specifies the length of the string.

cbString

Specifies the number of characters in the string.

lpSize

Points to a SIZE structure in which the dimensions of the string are to be returned.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The GetTextExtentPoint32 function uses the currently selected font to compute the dimensions of the string. The width and height, in logical units, are computed without considering any clipping.

Because some devices kern characters, the sum of the extents of the characters in a string may not be equal to the extent of the string.

The calculated string width takes into account the intercharacter spacing set by the SetTextCharacterExtra function.

See Also

GetTextExtentPoint, SetTextCharacterExtra, SIZE


GetTextFace

The GetTextFace function retrieves the typeface name of the font that is selected into the specified device context.

int GetTextFace(

HDC  hdc,	// handle of device context
int  nCount,	// length of buffer receiving typeface name
LPTSTR  lpFaceName	// address of buffer receiving typeface name
);
Parameters

hdc

Identifies the device context.

nCount

Specifies the size, in characters, of the buffer.

lpFaceName

Points to the buffer that is to receive the typeface name. If this parameter is NULL, the function returns the number of characters in the name, including the terminating null character.

Return Value

If the function succeeds, the return value is the number of characters copied to the buffer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The typeface name is copied as a null-terminated character string.

If the name is longer than the number of characters specified by the nCount parameter, the name is truncated.

See Also

GetTextAlign, GetTextColor, GetTextExtentPoint32, GetTextMetrics


GetTextMetrics

The GetTextMetrics function fills the specified buffer with the metrics for the currently selected font.

BOOL GetTextMetrics(

HDC  hdc,	// handle of device context
LPTEXTMETRIC  lptm	// address of text metrics structure
);
Parameters

hdc

Identifies the device context.

lptm

Points to the TEXTMETRIC structure that is to receive the metrics.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetTextAlign, GetTextExtent, GetTextFace, SetTextJustification, TEXTMETRIC


GetThreadContext

The GetThreadContext function retrieves the context of the specified thread.

BOOL GetThreadContext(

HANDLE  hThread,	// handle of thread with context
LPCONTEXT  lpContext	// address of context structure
);
Parameters

hThread

Identifies an open handle of a thread whose context is to be retrieved. 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 computer specific; two versions of the structure currently exist, one version for x86 processors and another for MIPS processors.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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 handle identified by the hThread parameter is typically being debugged, but the function can also operate when it is not being debugged.

See Also

CONTEXT, SetThreadContext


GetThreadDesktop

The GetThreadDesktop function returns a handle to the desktop associated with a specified thread.

HDESK GetThreadDesktop(

DWORD  dwThreadId	// thread identifier
);
Parameters

dwThreadId

Identifies the thread for which to return the desktop handle. The GetCurrentThreadId and CreateProcess functions return thread identifiers.

Return Value

If the function succeeds, the return value is the handle of the desktop associated with the specified thread. Remarks

The system associates a desktop with a thread when that thread is created. A thread can use the SetThreadDesktop function to change its desktop. The desktop associated with a thread must be on the window station associated with the thread's process.

The calling process can use the returned handle in calls to the GetUserObjectInformation, GetUserObjectSecurity, SetUserObjectInformation, and SetUserObjectSecurity functions.

See Also

GetCurrentThreadId, GetProcessWindowStation, GetUserObjectInformation, GetUserObjectSecurity, SetProcessWindowStation, SetThreadDesktop, SetUserObjectInformation, SetUserObjectSecurity


GetThreadLocale

The GetThreadLocale function returns the calling thread's current locale.

LCID GetThreadLocale(VOID)

Parameters

This function has no parameters.

Return Value

The function returns the calling thread's 32-bit LCID locale identifier.

Remarks

When a thread is created, it is given the system default thread locale. The system reads the system default thread locale from the registry when the system boots. This system default can be modified for future process and thread creation using Control Panel's International application.

See Also

SetThreadLocale, GetSystemDefaultLCID, GetUserDefaultLCID


GetThreadPriority

The GetThreadPriority function returns the priority value for the specified thread. This value, together with the priority class of the thread's process, determines the thread's base-priority level.

int GetThreadPriority(

HANDLE  hThread	// handle to thread
);
Parameters

hThread

Identifies the thread. The handle must have THREAD_QUERY_INFORMATION access.

Return Value

If the function succeeds, the return value is the thread's priority level.

If the function fails, the return value is THREAD_PRIORITY_ERROR_RETURN. To get extended error information, call GetLastError.

The thread's priority level is one of the following values:

Priority	Meaning
THREAD_PRIORITY_ABOVE_NORMAL
	Indicates 1 point above normal priority for the priority class.
THREAD_PRIORITY_BELOW_NORMAL
	Indicates 1 point below normal priority for the priority class.
THREAD_PRIORITY_HIGHEST
	Indicates 2 points above normal priority for the priority class.
THREAD_PRIORITY_IDLE
	Indicates a base-priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base-priority level of 16 for REALTIME_PRIORITY_CLASS processes.
THREAD_PRIORITY_LOWEST
	Indicates 2 points below normal priority for the priority class.
THREAD_PRIORITY_NORMAL
	Indicates normal priority for the priority class.
THREAD_PRIORITY_TIME_CRITICAL
	Indicates a base-priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base-priority level of 31 for REALTIME_PRIORITY_CLASS processes.
Remarks

Every thread has a base-priority level determined by the thread's priority value and the priority class of its process. The operating system uses the base-priority level of all executable threads to determine which thread gets the next slice of CPU time. Threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level will scheduling of threads at a lower level take place.

For a table that shows the base-priority levels for each combination of priority class and thread priority value, refer to the SetPriorityClass function.

See Also

GetPriorityClass, SetPriorityClass, SetThreadPriority


GetThreadSelectorEntry

The GetThreadSelectorEntry function retrieves a descriptor table entry for the specified selector and thread.

BOOL GetThreadSelectorEntry(

HANDLE  hThread,	// handle of thread that contains selector
DWORD  dwSelector,	// number of selector value to look up
LPLDT_ENTRY  lpSelectorEntry	// address of selector entry structure
);
Parameters

hThread

Identifies a handle of the thread containing the specified selector. 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.

Return Value

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, call GetLastError.

Remarks

GetThreadSelectorEntry is only functional on x86-based systems. For systems that are not x86-based, the function returns FALSE.

Debuggers use this function to convert segment-relative addresses to linear virtual addresses. The ReadProcessMemory and WriteProcessMemory functions use linear virtual addresses.

See Also

ReadProcessMemory, WriteProcessMemory


GetThreadTimes

The GetThreadTimes function obtains timing information about a specified thread.

BOOL GetThreadTimes(

HANDLE  hThread,	// specifies the thread of interest
LPFILETIME  lpCreationTime,	// when the thread was created
LPFILETIME  lpExitTime,	// when the thread was destroyed
LPFILETIME  lpKernelTime,	// time the thread has spent in kernel mode
LPFILETIME  lpUserTime	// time the thread has spent in user mode
);
Parameters

hThread

An open handle that specifies the thread whose timing information is sought. This handle must be created with THREAD_QUERY_INFORMATION access.

lpCreationTime

Points to a FILETIME structure that receives the creation time of the thread.

lpExitTime

Points to a FILETIME structure that receives the exit time of the thread. If the thread has not exited, the content of this structure is undefined.

lpKernelTime

Points to a FILETIME structure that receives the amount of time that the thread has executed in kernel mode.

lpUserTime

Points to a FILETIME structure that receives the amount of time that the thread has executed in user mode.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

All times are expressed using FILETIME data structures. Such a structure contains two 32-bit values that combine to form a 64-bit count of 100-nanosecond time units.

Thread creation and exit times are points in time expressed as the amount of time that has elapsed since midnight on January 1, 1601 at Greenwich, England. The Win32 API provides several functions that an application can use to convert such values to more generally useful forms; see Time and Date Functions, and the functions noted in the following See Also section.

Thread kernel mode and user mode times are amounts of time. For example, if a thread has spent one second in kernel mode, this function will fill the FILETIME structure specified by lpKernelTime with a 64-bit value of ten million. That is the number of 100-nanosecond units in one second.

See Also

FILETIME, FileTimeToDosDateTime, FileTimeToLocalFileTime, FileTimeToSystemTime


GetThresholdEvent

The GetThresholdEvent function is not implemented in the Win32 API.

See Also

Beep, MessageBeep


GetThresholdStatus

The GetThresholdStatus function is not implemented in the Win32 API.

See Also

Beep, MessageBeep


GetTickCount

The GetTickCount function retrieves the number of milliseconds that have elapsed since Windows was started.

DWORD GetTickCount(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the number of milliseconds that have elapsed since Windows was started.

Remarks

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


GetTimeFormat

The GetTimeFormat function formats a time as a time string for a specified locale. The function formats either a specified time or the local system time.

int GetTimeFormat(

LCID  Locale,	// locale for which time is to be formatted
DWORD  dwFlags,	// flags specifying function options
CONST SYSTEMTIME *  lpTime,	// time to be formatted
LPCTSTR  lpFormat,	// time format string
LPTSTR  lpTimeStr,	// buffer for storing formatted string
int  cchTime	// size of buffer
);
Parameters

Locale

Specifies the locale for which the time string is to be formatted. If lpFormat is NULL, the function formats the string according to the time format for this locale. If lpFormat is not NULL, the function uses the locale only for information not specified in the format picture string (for example, the locale's time markers).

This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
dwFlags

A set of bit flags that specify various function options. You can specify a combination of the following flags:

Flag	Meaning
LOCALE_NOUSEROVERRIDE	If set, the function formats the string using the system default time format for the specified locale. If not set, the function formats the string using any user overrides to the locale's default time format. This flag cannot be set if lpFormat is non-NULL.
TIME_NOMINUTESORSECONDS	Do not use minutes or seconds.
TIME_NOSECONDS	Do not use seconds.
TIME_NOTIMEMARKER	Do not use a time marker.
TIME_FORCE24HOURFORMAT	Always use a 24-hour time format.
lpTime

Pointer to a SYSTEMTIME structure that contains the time information to be formatted. If this pointer is NULL, the function uses the current local system time.

lpFormat

Pointer to a format picture to use to form the time string. If lpFormat is NULL, the function uses the time format of the specified locale.

Use the following elements to construct a format picture string. If you use spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown (for example, "ss", not "SS"). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.

Picture	Meaning
h	Hours with no leading zero for single-digit hours; 12-hour clock
hh	Hours with leading zero for single-digit hours; 12-hour clock
H	Hours with no leading zero for single-digit hours; 24-hour clock
HH	Hours with leading zero for single-digit hours; 24-hour clock
m	Minutes with no leading zero for single-digit minutes
mm	Minutes with leading zero for single-digit minutes
s	Seconds with no leading zero for single-digit seconds
ss	Seconds with leading zero for single-digit seconds
t	One character time marker string, such as A or P
tt	Multicharacter time marker string, such as AM or PM
For example, to get the time string

"11:29:40 PM"

use the following picture string:

"hh':'mm':'ss tt"

lpTimeStr

Pointer to a buffer that receives the formatted time string.

cchTime

Specifies the size, in bytes (ANSI version) or characters (Unicode version), of the lpTimeStr buffer. If cchTime is zero, the function returns the number of bytes or characters required to hold the formatted time string, and the buffer pointed to by lpTimeStr is not used.

Return Value

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) written to the buffer pointed to by lpTimeStr. If the cchTime parameter is zero, the return value is the number of bytes or characters required to hold the formatted time string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

If a time marker exists and the TIME_NOTIMEMARKER flag is not set, the function localizes the time marker based on the specified locale identifier. Examples of time markers are "AM" and "PM" for US English.

The time values in the SYSTEMTIME structure pointed to by lpTime must be valid. The function checks each of the time values to determine that it is within the appropriate range of values. If any of the time values are outside the correct range, the function fails, and sets the last-error to ERROR_INVALID_PARAMETER.

The function ignores the date portions of the SYSTEMTIME structure pointed to by lpTime: wYear, wMonth, wDayOfWeek, and wDay.

If TIME_NOMINUTESORSECONDS or TIME_NOSECONDS is specified, the function removes the separator(s) preceding the minutes and/or seconds element(s).

If TIME_NOTIMEMARKER is specified, the function removes the separator(s) preceding and following the time marker.

If TIME_FORCE24HOURFORMAT is specified, the function displays any existing time marker, unless the TIME_NOTIMEMARKER flag is also set.

The function does not include milliseconds as part of the formatted time string.

To use the LOCALE_NOUSEROVERRIDE flag, lpFormat must be NULL.

No errors are returned for a bad format string. The function simply forms the best time string that it can. If more than two hour, minute, second, or time marker format pictures are passed in, then the function defaults to two. For example, the only time marker pictures that are valid are L"t" and L"tt" (the 'L' indicates a Unicode (16-bit characters) string). If L"ttt" is passed in, the function assumes L"tt".

See Also

GetDateFormat, SYSTEMTIME


GetTimeZoneInformation

The GetTimeZoneInformation function retrieves the current time-zone parameters. These parameters control the translations between Coordinated Universal Time (UTC) and local time.

DWORD GetTimeZoneInformation(

LPTIME_ZONE_INFORMATION  lpTimeZoneInformation	// address of time-zone settings
);
Parameters

lpTimeZoneInformation

Points to a TIME_ZONE_INFORMATION structure to receive the current time-zone parameters.

Return Value

If the function succeeds, the return value is one of the following values:

Value	Meaning
TIME_ZONE_ID_UNKNOWN	The operating system cannot determine the current time zone. This is usually because a previous call to the SetTimeZoneInformation function supplied only the bias (and no transition dates).
TIME_ZONE_ID_STANDARD	The operating system is operating in the range covered by the StandardDate member of the structure pointed to by the lpTimeZoneInformation parameter.
TIME_ZONE_ID_DAYLIGHT	The operating system is operating in the range covered by the DaylightDate member of the structure pointed to by the lpTimeZoneInformation parameter.
If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

All translations between UTC time and local time are based on the following formula:

UTC = local time + bias

The bias is the difference, in minutes, between UTC time and local time.

See Also

SetTimeZoneInformation, TIME_ZONE_INFORMATION


GetTokenInformation

The GetTokenInformation function retrieves a specified type of information about an access token. The calling process must have appropriate access rights to obtain the information.

BOOL GetTokenInformation(

HANDLE  TokenHandle,	// handle of access token
TOKEN_INFORMATION_CLASS  TokenInformationClass,	// type of information to retrieve
LPVOID  TokenInformation,	// address of retrieved information
DWORD  TokenInformationLength,	// size of information buffer
PDWORD  ReturnLength	// address of required buffer size
);
Parameters

TokenHandle

Identifies an access token from which information is retrieved.

TokenInformationClass

Specifies a variable of the TOKEN_INFORMATION_CLASS enumerated type identifying the type of information the function retrieves.

TokenInformation

Points to a buffer the function fills with the requested information. The structure put into this buffer depends upon the type of information specified by the TokenInformationClass parameter, as shown in the following list:

Token Information Class	Structure Returned
TokenUser	TOKEN_USER structure. TOKEN_QUERY access is needed to retrieve this information.
TokenGroups	TOKEN_GROUPS structure. TOKEN_QUERY access is needed to retrieve this information.
TokenPrivileges	TOKEN_PRIVILEGES structure. TOKEN_QUERY access is needed to retrieve this information.
TokenOwner	TOKEN_OWNER structure. TOKEN_QUERY access is needed to retrieve this information.
TokenPrimaryGroup	TOKEN_PRIMARY_GROUP structure. TOKEN_QUERY access is needed to retrieve this information.
TokenDefaultDacl	TOKEN_DEFAULT_DACL structure. TOKEN_QUERY access is needed to retrieve this information.
TokenSource	TOKEN_SOURCE structure. TOKEN_QUERY_SOURCE access is needed to retrieve this information.
TokenType	TOKEN_TYPE enumerated type. TOKEN_QUERY access is needed to retrieve this information.
TokenImpersonationLevel	SECURITY_IMPERSONATION_LEVEL enumerated type. TOKEN_QUERY access is needed to retrieve this information about a token. If the access token is not an impersonation token, the function fails.
TokenStatistics	TOKEN_STATISTICS structure. TOKEN_QUERY access is needed to retrieve this information.
The formats for the retrieved structures and enumerated types are listed in the following Remarks section.

TokenInformationLength

Specifies the size, in bytes, of the buffer pointed to by the TokenInformation parameter.

ReturnLength

Points to a variable receiving the actual number of bytes needed for the buffer pointed to by the TokenInformation parameter. If this value is larger than the value specified in the TokenInformationLength parameter, the function fails and stores no data in the buffer.

If the value of the TokenInformationClass parameter is TokenDefaultDacl and the token has no default access-control list, the function sets the variable pointed to by ReturnLength to zero and stores no data in the buffer.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AdjustTokenGroups, AdjustTokenPrivileges, OpenProcessToken, OpenThreadToken, SetTokenInformation, SECURITY_IMPERSONATION_LEVEL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


GetTopWindow

The GetTopWindow function examines the Z order of the child windows associated with the specified parent window and retrieves the handle of the child window at the top of the Z order.

HWND GetTopWindow(

HWND  hWnd	// handle of parent window
);
Parameters

hWnd

Identifies the parent window whose child windows are to be examined. If this parameter is NULL, the function returns a handle of the window at the top of the Z order.

Return Value

If the function succeeds, the return value is the handle of the child window at the top of the Z order. If the specified window has no child windows, the return value is NULL. To get extended error information, use the GetLastError function.

See Also

GetNextWindow, GetWindow


GetTypeByName

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

INT GetTypeByName(

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

lpServiceName

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

lpServiceType

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

Return Value

If the function succeeds, the return value is zero.

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

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

GetNameByType


GetUpdateRect

The GetUpdateRect function retrieves the coordinates of the smallest rectangle that completely encloses the update region of the specified window. If the window was created with the CS_OWNDC style and the mapping mode is not MM_TEXT, GetUpdateRect retrieves the rectangle in logical coordinates. Otherwise, it retrieves the rectangle in client coordinates. If there is no update region, GetUpdateRect retrieves an empty rectangle (sets all coordinates to zero).

BOOL GetUpdateRect(

HWND  hWnd,	// handle of window
LPRECT  lpRect,	// address of update rectangle coordinates
BOOL  bErase	// erase flag
);
Parameters

hWnd

Identifies the window with an update region that is to be retrieved.

lpRect

Points to the RECT structure that receives the coordinates of the enclosing rectangle.

An application can set this parameter to NULL to determine whether an update region exists for the window. If this parameter is NULL, GetUpdateRect returns nonzero if an update region exists, and zero if one does not. This provides a simple and efficient means of determining whether a WM_PAINT message resulted from an invalid area.

bErase

Specifies whether the background in the update region is to be erased. If this parameter is TRUE and the update region is not empty, GetUpdateRect sends a WM_ERASEBKGND message to the specified window to erase the background.

Return Value

If the update region is not empty, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The update rectangle retrieved by the BeginPaint function is identical to that retrieved by GetUpdateRect.

BeginPaint automatically validates the update region, so any call to GetUpdateRect made immediately after the call to BeginPaint retrieves an empty update region.

See Also

BeginPaint, GetUpdateRgn, InvalidateRect, RECT, UpdateWindow, ValidateRect


GetUpdateRgn

The GetUpdateRgn function retrieves the update region of a window by copying it into the specified region. The coordinates of the update region are relative to the upper-left corner of the window (that is, they are client coordinates).

int GetUpdateRgn(

HWND  hWnd,	// handle of window
HRGN  hRgn,	// handle of region
BOOL  bErase	// erase background flag
);
Parameters

hWnd

Identifies the window with an update region that is to be retrieved.

hRgn

Identifies the region to receive the update region.

bErase

Specifies whether the window background should be erased and whether nonclient areas of child windows should be drawn. If this parameter is FALSE, no drawing is done.

Return Value

The return value indicates the complexity of the resulting region; it can be one of the following values:

Value	Meaning
COMPLEXREGION	Region consists of more than one rectangle.
ERROR	An error occurred.
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
Remarks

The BeginPaint function automatically validates the update region, so any call to GetUpdateRgn made immediately after the call to BeginPaint retrieves an empty update region.

See Also

GetUpdateRect, InvalidateRgn, UpdateWindow, ValidateRgn


GetUserDefaultLangID

The GetUserDefaultLangID function retrieves the user default language identifier.

LANGID GetUserDefaultLangID(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the user default language identifier.

See Also

GetSystemDefaultLangID, MAKELANGID


GetUserDefaultLCID

The GetUserDefaultLCID function retrieves the user default locale identifier.

LCID GetUserDefaultLCID(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is the user default locale identifier.

See Also

GetLocaleInfo, GetSystemDefaultLCID, MAKELCID


GetUserName

The GetUserName function retrieves the user name of the current thread. This is the name of the user currently logged onto the system.

BOOL GetUserName(

LPTSTR  lpBuffer,	// address of name buffer
LPDWORD  nSize	// address of size of name buffer
);
Parameters

lpBuffer

Points to the buffer to receive the null-terminated string containing the user's logon name. If this buffer is not large enough to contain the entire user name, the function fails.

nSize

Pointer to a DWORD that, on input, specifies the maximum size, in characters, of the buffer specified by the lpBuffer parameter. If this buffer is not large enough to contain the entire user name, the function fails. If the function succeeds, it will place the number of characters copied to the buffer into the DWORD that nSize points to.

Return Value

If the function succeeds, the return value is TRUE, and the variable pointed to by nSize contains the number of characters copied to the buffer specified by lpBuffer, including the terminating null character.

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

Remarks

If the current thread is impersonating another client, the GetUserName function returns the user name of the client that the thread is impersonating.

See Also

LookupAccountName


GetUserObjectInformation  (preliminaryWindows NT)
GetUserObjectInformation  (preliminary−Windows NT)

The GetUserObjectInformation function returns information about a window station or desktop object.

BOOL GetUserObjectInformation(

HANDLE hObj	// handle of object to get information for
int nIndex	// type of information to get
PVOID pvInfo	// points to buffer that receives the information
DWORD nLength	// size, in bytes, of pvInfo buffer
LPDWORD lpnLengthNeeded	// receives required size, in bytes, of pvInfo buffer
);
Parameters

hObj

Identifies the window station or desktop object for which to return information. This can be an HDESK or HWINSTA handle (for example, a handle returned by CreateWindowStation, OpenWindowStation, CreateDesktop, or OpenDesktop).

nIndex

Specifies the object information to be retrieved. The parameter must be one of the following values:

Value	Description
UOI_FLAGS	Returns handle flags. The pvInfo parameter must point to a USEROBJECTFLAGS structure.
UOI_NAME	Returns a string containing the name of the object.
UOI_TYPE	Returns a string containing the type name of the object.
pvInfo

Points to a buffer to receive the object information.

nLength

Specifies the size, in bytes, of the buffer pointed to by the pvInfo parameter.

lpnLengthNeeded

Points to a variable receiving the number of bytes required to store the requested information. If this variable's value is greater than the value of the nLength parameter when the function returns, the function returns FALSE, and none of the information is copied to the pvInfo buffer. If the value of the variable pointed to by lpnLengthNeeded is less than or equal to the value of nLength, the entire information block is copied.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateDesktop, CreateWindowStation, GetUserObjectSecurity, OpenDesktop, OpenWindowStation, SetUserObjectInformation, SetUserObjectSecurity, USEROBJECTFLAGS


GetUserObjectSecurity

The GetUserObjectSecurity function retrieves security information for the specified user object.

BOOL GetUserObjectSecurity(

HANDLE  hObj,	// handle of user object
PSECURITY_INFORMATION  pSIRequested,	// address of requested security information
PSECURITY_DESCRIPTOR  pSID,	// address of security descriptor
DWORD  nLength,	// size of buffer for security descriptor
LPDWORD  lpnLengthNeeded	// address of required size of buffer
);
Parameters

hObj

Identifies the user object for which to return security information.

pSIRequested

Points to a SECURITY_INFORMATION structure specifying the security information being requested.

pSID

Points to a SECURITY_DESCRIPTOR structure in self-relative format that contains the requested information when the function returns.

nLength

Specifies the length, in bytes, of the buffer pointed to by the pSID parameter.

lpnLengthNeeded

Points to a variable receiving the number of bytes required to store the complete security descriptor. If this variable's value is greater than the value of the nLength parameter when the function returns, the function returns FALSE and none of the security descriptor is copied to the buffer. Otherwise, the entire security descriptor is copied.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreatePrivateObjectSecurity, GetKernelObjectSecurity, GetPrivateObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetUserObjectSecurity


GetVersion

The GetVersion function returns the current version number of Windows and information about the operating system platform. This function has been superseded by GetVersionEx, which is the preferred method for obtaining system version number information. New applications should use GetVersionEx. The GetVersionEx function was developed because many existing Windows applications err when examining the DWORD return value of a GetVersion function call, transposing the major and minor version numbers packed into that DWORD. The GetVersionEx function forces applications to explicitly examine each element of version information, and allows for future enhancements to that information.

DWORD GetVersion(VOID)

Parameters

This function has no parameters.

Return Value

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-order word contains the version number of Windows. The high-order byte specifies the minor version (revision) number, in hexadecimal notation. The low-order byte specifies the major version number, in hexadecimal notation.

The high-order word contains the information about the operating system platform. The high bit specifies the platform, as follows:

Value	Platform
0	Microsoft Windows NT
1	Microsoft Win32s with Windows 3.1
The remaining bits in the high word are reserved.

Remarks

This function does not return the current version number of MS-DOS.

See Also

GetVersionEx


GetVersionEx

The GetVersionEx function obtains extended information about the version of the operating system that is currently running.

BOOL GetVersionEx(

LPOSVERSIONINFO  lpVersionInformation	// points to version information structure
);
Parameters

lpVersionInformation

Points to an OSVERSIONINFO data structure that the function fills with operating system version information.

Before calling the GetVersionEx function, set the dwOSVersionInfoSize member of the OSVERSIONINFO data structure to sizeof(OSVERSIONINFO).

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

The function fails if the value of the dwOSVersionInfoSize member of the passed OSVERSIONINFO structure is too small. A value that is too small indicates that the data structure is not large enough to contain the current version information.

Remarks

The GetVersionEx function supersedes the GetVersion function and is the preferred method for obtaining operating system version number information. New applications should use the GetVersionEx function rather than the GetVersion function.

See Also

OSVERSIONINFO


GetViewportExt

The GetViewportExt function is not implemented in the Win32 API. This function is included for compatability with 16-bit versions of Windows. Win32-based applications should use the GetViewportExtEx function.


GetViewportExtEx

The GetViewportExtEx function retrieves the x-extents and y-extents of the current viewport for the specified device context.

BOOL GetViewportExtEx(

HDC  hdc,	// handle of device context
LPSIZE  lpSize	// address of structure receiving viewport dimensions
);
Parameters

hdc

Identifies the device context.

lpSize

Points to a SIZE structure. The x- and y-extents, in device units, are placed in this structure.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

GetWindowExtEx, SetViewportExtEx, SetWindowExtEx


GetViewportOrg

The GetViewportOrg function has is not implemented in the Win32 API. This function is included for compatability with 16-bit versions of Windows. Win32-based applications should use the GetViewportOrgEx function.


GetViewportOrgEx

The GetViewportOrgEx function retrieves the x-coordinates and y-coordinates of the viewport origin for the specified device context.

BOOL GetViewportOrgEx(

HDC  hdc,	// handle of device context
LPPOINT  lpPoint	// address of structure receiving the viewport origin
);
Parameters

hdc

Identifies the device context.

lpPoint

Points to a POINT structure that receives the origin coordinates.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

GetWindowOrgEx, POINT, SetViewportOrgEx, SetWindowOrgEx


GetVolumeInformation

The GetVolumeInformation function returns information about a file system and volume whose root directory is specified.

BOOL GetVolumeInformation(

LPCTSTR  lpRootPathName,	// address of root directory of the file system
LPTSTR  lpVolumeNameBuffer,	// address of name of the volume
DWORD  nVolumeNameSize,	// length of lpVolumeNameBuffer
LPDWORD  lpVolumeSerialNumber,	// address of volume serial number
LPDWORD  lpMaximumComponentLength,	// address of system's maximum filename length
LPDWORD  lpFileSystemFlags,	// address of file system flags
LPTSTR  lpFileSystemNameBuffer,	// address of name of file system
DWORD  nFileSystemNameSize	// length of lpFileSystemNameBuffer
);
Parameters

lpRootPathName

Points to a string that contains the root directory of the volume to be described. If this parameter is NULL, the root of the current directory is used.

lpVolumeNameBuffer

Points to a buffer that receives the name of the specified volume.

nVolumeNameSize

Specifies the length, in characters, of the volume name buffer. This parameter is ignored if the volume name buffer is not supplied.

lpVolumeSerialNumber

Points to a variable that receives the volume serial number. This parameter can be NULL if the serial number is not required.

lpMaximumComponentLength

Points to a doubleword value that receives the maximum length, in characters, of a filename component supported by the specified file system. A filename component is that portion of a filename between backslashes.

The value stored in variable pointed to by *lpMaximumComponentLength is used to indicate that long names are supported by the specified file system. For example, for a FAT file system supporting long names, the function stores the value 255, rather than the previous 8.3 indicator. Long names can also be supported on systems that use the NTFS and HPFS file systems.

lpFileSystemFlags

Points to a doubleword that receives flags associated with the specified file system. This parameter can be any combination of the following flags, with one exception: FS_FILE_COMPRESSION and FS_VOL_IS_COMPRESSED are mutually exclusive.

Value	Meaning
FS_CASE_IS_PRESERVED	If this flag is set, the file system preserves the case of filenames when it places a name on disk.
FS_CASE_SENSITIVE	If this flag is set, the file system supports case-sensitive filenames.
FS_UNICODE_STORED_ON_DISK	If this flag is set, the file system supports Unicode in filenames as they appear on disk.
FS_PERSISTENT_ACLS	If this flag is set, the file system preserves and enforces ACLs. For example, NTFS preserves and enforces ACLs, HPFS and FAT do not.
FS_FILE_COMPRESSION	The file system supports file-based compression.
FS_VOL_IS_COMPRESSED	The specified volume is a compressed volume; for example, a DoubleSpace volume.
lpFileSystemNameBuffer

Points to a buffer that receives the name of the file system (such as FAT, 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.

Return Value

If all the requested information is retrieved, the return value is TRUE; otherwise, it is FALSE. To get extended error information, call GetLastError.

Remarks

The FS_VOL_IS_COMPRESSED flag is the only indicator of volume-based compression. The file system name is not altered to indicate compression. This flag comes back set on a DoubleSpace volume, for example. With volume-based compression, an entire volume is either compressed or not compressed.

The FS_FILE_COMPRESSION flag indicates whether a file system supports file-based compression. With file-based compression, individual files can be compressed or not compressed.

The FS_FILE_COMPRESSION and FS_VOL_IS_COMPRESSED flags are mutually exclusive; both bits cannot come back set.

The maximum component length value, stored in the DWORD variable pointed to by lpMaximumComponentLength, is the only indicator that a volume supports longer-than-normal FAT (or other file system) file names. The file system name is not altered to indicate support for long file names.

The GetCompressedFileSize function obtains the compressed size of a file. The GetFileAttributes function can determine whether an individual file is compressed.

See Also

GetCompressedFileSize, GetFileAttributes, SetVolumeLabel


GetWindow

The GetWindow function retrieves the handle of a window that has the specified relationship to the specified window.

HWND GetWindow(

HWND  hWnd,	// handle of original window
UINT  uCmd	// relationship flag
);
Parameters

hWnd

Identifies a window. The window handle retrieved is relative to this window, based on the value of the uCmd parameter.

uCmd

Specifies the relationship between the specified window and the window whose handle is to be retrieved. This parameter can be one of the following values:

Value	Meaning
GW_CHILD	The retrieved handle identifies the child window at the top of the Z order, if the specified window is a parent window; otherwise, the retrieved handle is NULL. The function examines only child windows of the specified window. It does not examine descendant windows.
GW_HWNDFIRST	The retrieved handle identifies the window at the top of the Z order. If the specified window is a topmost window, the handle identifies the topmost window at the top of the Z order. If the specified window is a top-level window, the handle identifies the top-level window at the top of the Z order. If the specified 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 specified window is a topmost window, the handle identifies the topmost window at the bottom of the Z order. If the specified window is a top-level window, the handle identifies the top-level window at the bottom of the Z order. If the specified 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 specified window in the Z order. If the specified window is a topmost window, the handle identifies the topmost window below the specified window. If the specified window is a top-level window, the handle identifies the top-level window below the specified window. If the specified window is a child window, the handle identifies the sibling window below the specified window.
GW_HWNDPREV	The retrieved handle identifies the window above the specified window in the Z order. If the specified window is a topmost window, the handle identifies the topmost window above the specified window. If the specified window is a top-level window, the handle identifies the top-level window above the specified window. If the specified window is a child window, the handle identifies the sibling window above the specified window.
GW_OWNER	The retrieved handle identifies the specified window's owner window, if any.
Return Value

If the function succeeds, the return value is a window handle. If no window exists with the specified relationship to the specified window, the return value is NULL. To get extended error information, call GetLastError.

See Also

GetActiveWindow, GetNextWindow, GetTopWindow


GetWindowContextHelpId  (preliminaryWindows NT)
GetWindowContextHelpId  (preliminary−Windows NT)

The GetWindowContextHelpId function retrieves the help context identifier, if any, associated with the specified window.

DWORD GetWindowContextHelpId(

HWND  hwnd
);
Parameters

hwnd

Handle to the window for which the help context identifier is to be retrieved.

Return Value

Returns the help context identifier if the window has one or zero otherwise.


GetWindowDC

The GetWindowDC function retrieves the device context (DC) for the entire window, including title bar, menus, and scroll bars. A window device context permits painting anywhere in a window, because the origin of the device context is the upper-left corner of the window instead of the client area.

GetWindowDC assigns default attributes to the window device context each time it retrieves the device context. Previous attributes are lost.

HDC GetWindowDC(

HWND  hWnd	// handle of window
);
Parameters

hWnd

Identifies the window with a device context that is to be retrieved.

Return Value

If the function succeeds, the return value is the handle of a device context for the specified window.

If the function fails, the return value is NULL, indicating an error or an invalid hWnd parameter.

Remarks

GetWindowDC is intended for special painting effects within a window's nonclient area. Painting in nonclient areas of any window is not recommended.

The GetSystemMetrics function can be used to retrieve the dimensions of various parts of the nonclient area, such as the title bar, menu, and scroll bars.

After painting is complete, the ReleaseDC function must be called to release the device context. Not releasing the window device context has serious effects on painting requested by applications.

See Also

BeginPaint, GetDC, GetSystemMetrics, ReleaseDC


GetWindowExt

The GetWindowExt function is not implemented in the Win32 API. This function is included for compatability with 16-bit versions of Windows. Win32-based applications should use the GetWindowExtEx function.


GetWindowExtEx

This function retrieves the x-extents and y-extents of the window for the specified device context.

BOOL GetWindowExtEx(

HDC  hdc,	// handle of device context
LPSIZE  lpSize	// address of structure receiving window extents
);
Parameters

hdc

Identifies the device context.

lpSize

Points to a SIZE structure. The x- and y-extents in page-space units are placed in this structure.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

GetViewportExtEx, SetViewportExtEx, SetWindowExtEx


GetWindowLong

The GetWindowLong function retrieves information about the specified window. The function also retrieves the 32-bit (long) value at the specified offset into the extra window memory of a window.

LONG GetWindowLong(

HWND  hWnd,	// handle of window
int  nIndex	// offset of value to retrieve
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based offset to the value to be retrieved. Valid values are in the range zero through the number of bytes of extra window memory, minus four; for example, if you specified 12 or more bytes of extra memory, a value of 8 would be an index to the third 32-bit integer. To retrieve any other value, specify one of the following values:

Value	Action
GWL_EXSTYLE	Retrieves the extended window styles.
GWL_STYLE	Retrieves the window styles.
GWL_WNDPROC	Retrieves the address of the window procedure, or a handle representing the address of the window procedure. You must use the CallWindowProc function to call the window procedure.
GWL_HINSTANCE	Retrieves the handle of the application instance.
GWL_HWNDPARENT	Retrieves the handle of the parent window, if any.
GWL_ID	Retrieves the identifier of the window.
GWL_USERDATA	Retrieves the 32-bit value associated with the window. Each window has a corresponding 32-bit value intended for use by the application that created the window.
The following values are also available when the hWnd parameter identifies a dialog box:

Value	Action
DWL_DLGPROC	Retrieves the address of the dialog box procedure, or a handle representing the address of the dialog box procedure. You must use the CallWindowProc function to call the dialog box procedure.
DWL_MSGRESULT	Retrieves the return value of a message processed in the dialog box procedure.
DWL_USER	Retrieves extra information private to the application, such as handles or pointers.
Return Value

If the function succeeds, the return value is the requested 32-bit value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the WNDCLASS structure used with the RegisterClass function.

See Also

CallWindowProc, GetWindowWord, RegisterClass, SetParent, SetWindowLong, SetWindowWord, WNDCLASS


GetWindowOrg

The GetWindowOrg function is not implemented in the Win32 API. This function is included for compatability with 16-bit versions of Windows. Win32-based applications should use the GetWindowOrgEx function.


GetWindowOrgEx

The GetWindowOrgEx function retrieves the x-coordinates and y-coordinates of the window origin for the specified device context.

BOOL GetWindowOrgEx(

HDC  hdc,	// handle of device context
LPPOINT  lpPoint	// address of structure receiving the window origin
);
Parameters

hdc

Identifies the device context.

lpPoint

Points to a POINT structure that receives the coordinates, in page units, of the window origin.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

GetViewportOrgEx, SetViewportOrgEx, SetWindowOrgEx


GetWindowPlacement

The GetWindowPlacement function retrieves the show state and the restored, minimized, and maximized positions of the specified window.

BOOL GetWindowPlacement(

HWND  hWnd,	// handle of window
WINDOWPLACEMENT *  lpwndpl	// address of structure for position data
);
Parameters

hWnd

Identifies the window.

lpwndpl

Points to the WINDOWPLACEMENT structure that receives the show state and position information.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The flags member of WINDOWPLACEMENT retrieved by this function is always zero. If the window identified by the hWnd parameter is maximized, the showCmd member is SW_SHOWMAXIMIZED. If the window is minimized, showCmd is SW_SHOWMINIMIZED. Otherwise, it is SW_SHOWNORMAL.

See Also

SetWindowPlacement, WINDOWPLACEMENT


GetWindowRect

The GetWindowRect function retrieves the dimensions of the bounding rectangle of the specified window. The dimensions are given in screen coordinates that are relative to the upper-left corner of the screen.

BOOL GetWindowRect(

HWND  hWnd,	// handle of window
LPRECT  lpRect	// address of structure for window coordinates
);
Parameters

hWnd

Identifies the window.

lpRect

Points to a RECT structure that receives the screen coordinates of the upper-left and lower-right corners of the window.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetClientRect, RECT


GetWindowRgn  (preliminaryWindows NT)
GetWindowRgn  (preliminary−Windows NT)

The GetWindowRgn function obtains a copy of the window region of a window. The window region of a window is set by calling the SetWindowRgn function. The window region determines the area within the window where the operating system permits drawing. The operating system does not display any portion of a window that lies outside of the window region

int GetWindowRgn(

HWND  hWnd,	// handle to window whose window region is to be obtained
HRGN  hRgn	// handle to region that receives a copy of the window region
);
Parameters

hWnd

Handle to the window whose window region is to be obtained.

hrgn

Handle to a region. This region receives a copy of the window region.

Return Value

The return value specifies the type of the region that the function obtains. It can be one of the following values:

Value	Meaning
NULLREGION	The region is empty.
SIMPLEREGION	The region is a single rectangle.
COMPLEXREGION	The region is more than one rectangle.
ERROR	An error occurred; the region is unaffected.
Comments

The coordinates of a window's window region are relative to the upper-left corner of the window, not the client area of the window.

To set the window region of a window, call the SetWindowRgn function.

See Also

SetWindowRgn


GetWindowsDir

The GetWindowsDir function is not implemented in the Win32 API. This function is included for compatability with 16-bit versions of Windows. Win32-based applications should use the GetWindowsDirectory function to determine the Windows directory.


GetWindowsDirectory

The GetWindowsDirectory function retrieves the path of the Windows directory. The Windows directory contains such files as Windows-based applications, initialization files, and Help files.

UINT GetWindowsDirectory(

LPTSTR  lpBuffer,	// address of buffer for Windows directory
UINT  uSize	// size of directory buffer
);
Parameters

lpBuffer

Points to the buffer to receive the null-terminated string containing the path. This path does not end with a backslash unless the Windows directory is the root directory. For example, if the Windows directory is named WINDOWS on drive C, the path of the Windows directory retrieved by this function is C:\WINDOWS. If Windows was installed in the root directory of drive C, the path retrieved is C:\.

uSize

Specifies the maximum size, in characters, of the buffer specified by the lpBuffer parameter. This value should be set to at least MAX_PATH to allow sufficient room in the buffer for the path.

Return Value

If the function succeeds, the return value is the length, in characters, of the string copied to the buffer, not including the terminating null character.

If the length is greater than the size of the buffer, the return value is the size of the buffer required to hold the path.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The Windows directory is the directory where an application should store initialization and help files. If the user is running a shared version of Windows, the Windows directory is guaranteed to be private for each user.

If an application creates other files that it wants to store on a per-user basis, it should place them in the directory specified by the HOMEPATH environment variable. This directory will be different for each user, if so specified by an administrator, via the User Manager administrative tool. HOMEPATH always specifies either the user's home directory, which is guaranteed to be private for each user, or a default directory (for example, C:\USERS\DEFAULT) where the user will have all access.

See Also

GetCurrentDirectory, GetSystemDirectory


GetWindowTask

The GetWindowTask function is not implemented in the WIn32 API.

To maintain compatibility with 16-bit applications, GetWindowTask has been replaced with a macro that calls GetWindowThreadProcessId. Earlier applications can continue to call GetWindowTask as previously documented, but new applications should use GetWindowThreadProcessId.

Remarks

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


GetWindowText

The GetWindowText function copies the text of the specified window's title bar (if it has one) into a buffer. If the specified window is a control, the text of the control is copied.

int GetWindowText(

HWND  hWnd,	// handle of window or control with text
LPTSTR  lpString,	// address of buffer for text
int  nMaxCount	// maximum number of characters to copy
);
Parameters

hWnd

Identifies the window or control containing the text.

lpString

Points to the buffer that will receive the text.

nMaxCount

Specifies the maximum number of characters to copy to the buffer. If the text exceeds this limit, it is truncated.

Return Value

If the function succeeds, the return value is the length, in characters, of the copied string, not including the terminating null character. If the window has no title bar or text, if the title bar is empty, or if the window or control handle is invalid, the return value is zero. To get extended error information, call GetLastError.

This function cannot retrieve the text of an edit control in another application.

Remarks

This function causes a WM_GETTEXT message to be sent to the specified window or control.

This function cannot retrieve the text of an edit control in another application.

See Also

GetWindowTextLength, SetWindowText, WM_GETTEXT


GetWindowTextLength

The GetWindowTextLength function retrieves the length, in characters, of the specified window's title bar text (if the window has a title bar). If the specified window is a control, the function retrieves the length of the text within the control.

int GetWindowTextLength(

HWND  hWnd	// handle of window or control with text
);
Parameters

hWnd

Identifies the window or control.

Return Value

If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

If the window has no text, the return value is zero. To get extended error information, call GetLastError.

Remarks

This function causes a WM_GETTEXTLENGTH message to be sent to the specified window or control.

Under certain conditions, the GetWindowTextLength function may return a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the operating system allowing for the possible existence of DBCS characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode. It can also occur when an application uses the ANSI flavor of GetWindowTextLength with a window whose window procedure is Unicode, or the Unicode flavor with a window whose window procedure is ANSI.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function

See Also

CB_GETLBTEXT, GetWindowText, LB_GETTEXT, SetWindowText, WM_GETTEXT, WM_GETTEXTLENGTH


GetWindowThreadProcessId

The GetWindowThreadProcessId function retrieves the identifier of the thread that created the specified window and, optionally, the identifier of the process that created the window. This function supersedes the GetWindowTask function.

DWORD GetWindowThreadProcessId(

HWND  hWnd,	// handle of window
LPDWORD  lpdwProcessId	// address of variable for process identifier
);
Parameters

hWnd

Identifies the window.

lpdwProcessId

Points to a 32-bit value that receives the process identifier. If this parameter is not NULL, GetWindowThreadProcessId copies the identifier of the process to the 32-bit value; otherwise, it does not.

Return Value

The return value is the identifier of the thread that created the window.

Remarks

This function replaces the GetWindowTask function of Windows version 3.x.


GetWindowWord

The GetWindowWord function retrieves a 16-bit (word) value at the specified offset into the extra window memory for the specified window.

WORD GetWindowWord(

HWND  hWnd,	// handle of window
int  nIndex	// offset of value to retrieve
);
Parameters

hWnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based byte offset of the value to be retrieved. Valid values are in the range zero through the number of bytes of extra window memory, minus two; for example, if you specified 10 or more bytes of extra window memory, a value of 8 would be an index to the fifth 16-bit integer.

Return Value

If the function succeeds, the return value is the requested 16-bit value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the WNDCLASS structure used with the RegisterClass function.

The GWW_ values are obsolete in Win32. You must use the GetWindowLong function to retrieve information about the window.

See Also

GetParent, GetWindowLong, RegisterClass, SetParent, SetWindowLong, SetWindowWord, WNDCLASS


GetWinFlags

The GetWinFlags function is not implemented in the Win32 API. Win32-based applications should use the GetSystemInfo function.


GetWinMetaFileBits

The GetWinMetaFileBits function converts the enhanced-format records from a metafile into Windows-format records and stores the converted records in the specified buffer.

UINT GetWinMetaFileBits(

HENHMETAFILE  hemf,	// handle of the enhanced metafile
UINT  cbBuffer,	// buffer size
LPBYTE  lpbBuffer,	// pointer to buffer
INT  fnMapMode,	// mapping mode
HDC  hdcRef	// handle of reference device context
);
Parameters

hemf

Identifies the enhanced metafile.

cbBuffer

Specifies the size, in bytes, of the buffer into which the converted records are to be copied.

lpbBuffer

Points to the buffer into which the converted records are to be copied. If lpbBuffer is NULL, GetWinMetaFileBits returns the the number of bytes required to store the converted metafile records.

fnMapMode

Specifies the mapping mode to use in the converted metafile.

hdcRef

Identifies the reference device context.

Return Value

If the function succeeds and the buffer pointer is NULL, the return value is the number of bytes required to store the converted records; if the function succeeds and the buffer pointer is a valid pointer, the return value is the size of the metafile data in bytes.

If the function fails, the return value is zero.

Remarks

This function converts an enhanced metafile into a Windows-format metafile so that its picture can be displayed in an application that recognizes the older format.

Windows uses the reference device context to determine the resolution of the converted metafile.

The GetWinMetaFileBits function does not invalidate the enhanced metafile handle. An application should call the DeleteEnhMetaFile function to release the handle when it is no longer needed.

Due to the limitations of the Windows-format metafile, some information can be lost in the retrieved metafile contents. For example, an original call to the PolyBezier function in the enhanced metafile may be converted into a call to the Polyline function in the Windows-format metafile, because there is no equivalent PolyBezier function in the Windows format.

Windows 3.x applications define the viewport origin and extents of a picture stored in a Windows-format metafile. As a result, the Windows-format records created by GetWinMetaFileBits do not contain the 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, PolyBezier, Polyline, SetMapMode, SetViewportOrg, SetViewportExt, SetWindowExt


GetWorldTransform

The GetWorldTransform function retrieves the current world-space to page-space transformation.

BOOL GetWorldTransform(

HDC  hdc,	// handle of device context
LPXFORM  lpXform	// address of structure receiving transformation
);
Parameters

hdc

Identifies the device context.

lpXform

Points to an XFORM structure that receives the current world-space to page-space transformation.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The precision of the transformation may be altered if an application calls the ModifyWorldTransform function prior to calling GetWorldTransform. (This is because the internal format for storing transformation values uses a higher precision than a FLOAT value.)

See Also

ModifyWorldTransform, SetWorldTransform


GlobalAddAtom

The GlobalAddAtom function adds a character string to the global atom table and returns a unique value (an atom) identifying the string.

ATOM GlobalAddAtom(

LPCTSTR  lpString	// address of string to add
);
Parameters

lpString

Points to the null-terminated string to be added. The string can have a maximum size of 255 bytes. Strings that differ only in case are considered identical. The case of the first string of this name added to the table is preserved and returned by the GlobalGetAtomName function.

Return Value

If the function succeeds, the return value is the newly created atom.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the string already exists in the global atom table, the atom for the existing string is returned and the atom's reference count is incremented.

The string associated with the atom is not deleted from memory until its reference count is zero. For more information, see the GlobalDeleteAtom function.

Global atoms are not deleted automatically when the application terminates. For every call to the GlobalAddAtom function, there must be a corresponding call to the GlobalDeleteAtom function.

GlobalAddAtom returns a string atom whose value is in the range 0xC000 through 0xFFFF.

If the lpString parameter has the form "#1234", GlobalAddAtom returns an integer atom whose value is the 16-bit representation of the decimal number specified in the string (0x04D2, in this example). If the decimal value specified is 0x0000 or a value in the range 0xC000 through 0xFFFF, the return value is zero, indicating an error. If lpString is in the range 0x0001 through 0xBFFF, the return value is the low-order word of lpString.

The MAKEINTATOM macro can be used to convert a WORD value into a string that can be added to the atom table by using the GlobalAddAtom function.

See Also

AddAtom, DeleteAtom, FindAtom, GetAtomName, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName, MAKEINTATOM


GlobalAlloc

The GlobalAlloc function allocates the specified number of bytes from the heap. In the linear Win32 API environment, there is no difference between the local heap and the global heap.

HGLOBAL GlobalAlloc(

UINT  uFlags,	// object allocation attributes
DWORD  dwBytes	// number of bytes to allocate
);
Parameters

uFlags

Specifies how to allocate memory. If zero is specified, the default is GMEM_FIXED. Except for the incompatible combinations that are specifically noted, any combination of the following flags can be used. To indicate whether the function allocates fixed or movable memory, specify one of the first four flags:

Flag	Meaning
GMEM_FIXED	Allocates fixed memory. This flag cannot be combined with the GMEM_MOVEABLE or GMEM_DISCARDABLE flag. The return value is a pointer to the memory block. To access the memory, the calling process simply casts the return value to a pointer.
GMEM_MOVEABLE	Allocates movable memory. This flag cannot be combined with the GMEM_FIXED flag. The return value is the handle of the memory object. The handle is a 32-bit quantity that is private to the calling process. To translate the handle into a pointer, use the GlobalLock function.
GPTR	Combines the GMEM_FIXED and GMEM_ZEROINIT flags.
GHND	Combines the GMEM_MOVEABLE and GMEM_ZEROINIT flags.
GMEM_DDESHARE	Allocates memory to be used by the dynamic data exchange (DDE) functions for a DDE conversation. Unlike Windows version 3. x, this memory is not shared globally. However, this flag is available for compatibility purposes. It may be used by some applications to enhance the performance of DDE operations and should, therefore, be specified if the memory is to be used for DDE.  Only processes that use DDE or the clipboard for interprocess communications should specify this flag.
GMEM_DISCARDABLE	Allocates discardable memory. This flag cannot be combined with the GMEM_FIXED flag. Some Win32-based applications may ignore this flag.
GMEM_LOWER	Ignored. This flag is provided only for compatibility with Windows version 3. x.
GMEM_NOCOMPACT	Does not compact or discard memory to satisfy the allocation request.
GMEM_NODISCARD	Does not discard memory to satisfy the allocation request.
GMEM_NOT_BANKED	Ignored. This flag is provided only for compatibility with Windows version 3. x.
GMEM_NOTIFY	Ignored. This flag is provided only for compatibility with Windows version 3. x.
GMEM_SHARE	Same as the GMEM_DDESHARE flag.
GMEM_ZEROINIT	Initializes memory contents to zero.
dwBytes

Specifies the number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies the GMEM_MOVEABLE flag, the function returns a handle to a memory object that is marked as discarded.

Return Value

If the function succeeds, the return value is the handle of the newly allocated memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If the heap does not contain sufficient free space to satisfy the request, GlobalAlloc returns NULL.

Because NULL is used to indicate an error, virtual address zero is never allocated. It is, therefore, easy to detect the use of a NULL pointer.

All memory is created with execute access; no special function is required to execute dynamically generated code.

Memory allocated with this function is guaranteed to be aligned on an 8-byte boundary.

The GlobalAlloc and LocalAlloc functions are limited to a combined total of 65,536 handles for GMEM_MOVEABLE and LMEM_MOVEABLE memory per process. This limitation does not apply to GMEM_FIXED or LMEM_FIXED memory.

If this function succeeds, it allocates at least the amount of memory requested. If the actual amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual number of bytes allocated, use the GlobalSize function.

See Also

GlobalFree, GlobalLock, GlobalReAlloc, GlobalSize, LocalAlloc


GlobalCompact

The GlobalCompact function is obsolete. It has no meaning in the 32-bit environment.


GlobalDeleteAtom

The GlobalDeleteAtom function decrements the reference count of a global string atom. If the atom's reference count reaches zero, GlobalDeleteAtom removes the string associated with the atom from the global atom table.

ATOM GlobalDeleteAtom(

ATOM  nAtom	// atom to delete
);
Parameters

nAtom

Identifies the atom and character string to be deleted.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is the nAtom parameter. To get extended error information, call GetLastError.

Remarks

A string atom's reference count specifies the number of times the string has been added to or removed from the atom table. The GlobalAddAtom function increments the reference count of a string that already exists in the global atom table each time it is called.

The only way to ensure that an atom has been deleted from the atom table is to call this function repeatedly until it fails. When the reference count is decremented to zero, the next GlobalFindAtom or GlobalDeleteAtom function call fails.

GlobalDeleteAtom has no effect on an integer atom (an atom created by using the MAKEINTATOM macro). The function always returns zero for an integer atom.

See Also

AddAtom, DeleteAtom, FindAtom, GlobalAddAtom, GlobalFindAtom, MAKEINTATOM


GlobalDiscard

The GlobalDiscard function discards the specified global memory block. The lock count of the memory object must be zero.

HGLOBAL GlobalDiscard(

HGLOBAL  hglbMem	// handle of global memory object
);
Parameters

hglbMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Value

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

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

GlobalDiscard discards only global objects that the calling process allocated with the GMEM_DISCARDABLE flag. If a process attempts to discard a fixed or locked object, the function fails.

Although GlobalDiscard discards the object's memory block, the handle of the object remains valid. A process can subsequently pass the handle to the GlobalReAlloc function to allocate another global memory block identified by the same handle.

See Also

GlobalAlloc, GlobalReAlloc


GlobalDosAlloc

The GlobalDosAlloc function has been deleted. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GlobalDosFree

The GlobalDosFree function has been deleted. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GlobalFindAtom

The GlobalFindAtom function searches the global atom table for the specified character string and retrieves the global atom associated with that string.

ATOM GlobalFindAtom(

LPCTSTR  lpString	// address of string to find
);
Parameters

lpString

Points to the null-terminated character string to search for.

Return Value

If the function succeeds, the return value is the global atom associated with the given string.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Even though Windows preserves the case of a string in an atom table as it was originally entered, the search performed by GlobalFindAtom is not case sensitive.

See Also

AddAtom, DeleteAtom, FindAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalGetAtomName


GlobalFix

The GlobalFix function is obsolete. It has no meaning in the 32-bit environment. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GlobalFlags

The GlobalFlags function returns information about the specified global memory object.

UINT GlobalFlags(

HGLOBAL  hMem	// handle of global memory object
);
Parameters

hMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Value

If the function succeeds, the return value is a 32-bit value specifying the allocation flags and the lock count for the memory object.

If the function fails, the return value is the GMEM_INVALID_HANDLE flag, indicating that the global handle is not valid. To get extended error information, call GetLastError.

Remarks

The low-order byte of the low-order word of the return value contains the lock count of the object. To retrieve the lock count from the return value, use the GMEM_LOCKCOUNT mask with the bitwise AND (&) operator. The lock count of memory objects allocated with the GMEM_FIXED flag is always zero.

The high-order byte of the low-order word of the return value indicates the allocation flags of the memory object. It can be zero or any combination of the following flags:

Flag	Meaning
GMEM_DDESHARE	Memory was allocated for use by the dynamic data exchange (DDE) functions. Unlike Windows version  3. x, this memory is not shared globally. However, this flag is available for compatibility purposes and may be used by some applications to enhance the performance of DDE operations. Only processes that use DDE or the clipboard for interprocess communications should specify this flag.
GMEM_DISCARDABLE	The object's memory block can be discarded.
GMEM_DISCARDED	The object's memory block has been discarded.
See Also

GlobalAlloc, GlobalDiscard, GlobalLock, GlobalReAlloc, GlobalUnlock, LocalFlags


GlobalFree

The GlobalFree function frees the specified global memory object and invalidates its handle.

HGLOBAL GlobalFree(

HGLOBAL  hMem	// handle of global memory object
);
Parameters

hMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Value

If the function succeeds, the return value is NULL.

If the function fails, the return value is equal to the handle of the global memory object. To get extended error information, call GetLastError.

Remarks

Heap corruption or an access violation exception (EXCEPTION_ACCESS_VIOLATION) may occur if the process tries to examine or modify the memory after it has been freed.

If the hgblMem parameter is NULL, GlobalFree fails and the system generates an access violation exception.

Both GlobalFree and LocalFree will free a locked memory object. A locked memory object has a lock count greater than zero. The GlobalLock function locks a global memory object and increments the lock count by one. The GlobalUnlock function unlocks it and decrements the lock count by one. To get the lock count of a global memory object, use the GlobalFlags function.

Windows NT: However, if an application is running under a debug (DBG) version of Windows NT, such as the one distributed on the SDK CD-ROM, both GlobalFree and LocalFree enter a breakpoint just before freeing a locked object. This lets a programmer double-check the intended behavior. Typing G while using the debugger in this situation lets the freeing operation occur.

See Also

GlobalAlloc, GlobalFlags, GlobalLock, GlobalReAlloc, GlobalUnlock, LocalFree


GlobalGetAtomName

The GlobalGetAtomName function retrieves a copy of the character string associated with the specified global atom.

UINT GlobalGetAtomName(

ATOM  nAtom,	// atom identifier
LPTSTR  lpBuffer,	// address of buffer for atom string
int  nSize	// size of buffer
);
Parameters

nAtom

Identifies the global atom associated with the character string to be retrieved.

lpBuffer

Points to the buffer for the character string.

nSize

Specifies the size, in characters, of the buffer.

Return Value

If the function succeeds, the return value is the length of the string copied to the buffer, in characters, not including the terminating null character.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The string returned for an integer atom (an atom created by the MAKEINTATOM macro) is a null-terminated string in which the first character is a pound sign (#) and the remaining characters represent the unsigned integer originally passed to MAKEINTATOM.

See Also

AddAtom, DeleteAtom, FindAtom, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, MAKEINTATOM


GlobalHandle

The GlobalHandle function retrieves the handle associated with the specified pointer to a global memory block.

HGLOBAL GlobalHandle(

LPCVOID  pMem	// address of global memory block
);
Parameters

pMem

Points to the first byte of the global memory block. This pointer is returned by the GlobalLock function.

Return Value

If the function succeeds, the return value is the handle of the specified global memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

When the GlobalAlloc function allocates a memory object with the GMEM_MOVEABLE flag, it returns the handle of the object. The GlobalLock function converts this handle into a pointer to the memory block, and GlobalHandle converts the pointer back into a handle.

See Also

GlobalAlloc, GlobalLock


GlobalLock

The GlobalLock function locks a global memory object and returns a pointer to the first byte of the object's memory block. The memory block associated with a locked memory object cannot be moved or discarded. For memory objects allocated with the GMEM_MOVEABLE flag, the function increments the lock count associated with the memory object.

LPVOID GlobalLock(

HGLOBAL  hMem	// handle of global memory object
);
Parameters

hMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Value

If the function succeeds, the return value is a pointer to the first byte of the memory block.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, GlobalLock increments the count by one, and the GlobalUnlock function decrements the count by one. For each call that a process makes to GlobalLock for an object, it must eventually call GlobalUnlock. Locked memory will not be moved or discarded, unless the memory object is reallocated by using the GlobalReAlloc function. The memory block of a locked memory object remains locked until its lock count is decremented to zero, at which time it can be moved or discarded.

Memory objects allocated with the GMEM_FIXED flag always have a lock count of zero. For these objects, the value of the returned pointer is equal to the value of the specified handle.

If the specified memory block has been discarded or if the memory block has a zero-byte size, this function returns NULL.

Discarded objects always have a lock count of zero.

See Also

GlobalAlloc, GlobalFlags, GlobalReAlloc, GlobalUnlock


GlobalLRUNewest

The GlobalLRUNewest function is obsolete. It has no meaning in the 32-bit environment. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GlobalLRUOldest

The GlobalLRUOldest function is obsolete. It has no meaning in the 32-bit environment. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GlobalMemoryStatus

The GlobalMemoryStatus function retrieves information about current available memory. The function returns information about both physical and virtual memory. This function supersedes the GetFreeSpace function.

VOID GlobalMemoryStatus(

LPMEMORYSTATUS  lpBuffer	// address of memory status structure
);
Parameters

lpBuffer

Points to a MEMORYSTATUS structure in which information about current memory availability is returned. Before calling this function, the calling process should set the dwLength member of this structure.

Return Value

This function does not return a value.

Remarks

An application can use the GlobalMemoryStatus function to determine how much memory it can allocate without severely impacting other applications.

The information returned is volatile, and there is no guarantee that two sequential calls to this function will return the same information.

See Also

MEMORYSTATUS


GlobalNotify

The GlobalNotify function is not implemented in the Win32 SDK. Win32-based applications should use the GlobalFlags function.


GlobalPageLock

The GlobalPageLock function is not implemented in the Win32 API. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GlobalPageUnlock

The GlobalPageUnlock function is not implemented in the Win32 API. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


GlobalReAlloc

The GlobalReAlloc function changes the size or attributes of a specified global memory object. The size can increase or decrease.

HGLOBAL GlobalReAlloc(

HGLOBAL  hMem,	// handle of global memory object
DWORD  dwBytes,	// new size of block
UINT  uFlags	// how to reallocate object
);
Parameters

hMem

Identifies the global memory object to be reallocated. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

dwBytes

Specifies the new size, in bytes, of the memory block. If this parameter is zero and the uFlags parameter specifies the GMEM_MOVEABLE flag, the function returns the handle of a memory object that is marked as discarded. If uFlags specifies the GMEM_MODIFY flag, this parameter is ignored.

uFlags

Specifies how to reallocate the global memory object. If the GMEM_MODIFY flag is specified, this parameter modifies the attributes of the memory object, and the dwBytes parameter is ignored. Otherwise, this parameter controls the reallocation of the memory object.

The GMEM_MODIFY flag can be combined with either or both of the following flags:

Flag	Meaning
GMEM_DISCARDABLE	Allocates discardable memory if the GMEM_MODIFY flag is also specified. This flag is ignored, unless the object was previously allocated as movable or the GMEM_MOVEABLE flag is also specified.
GMEM_MOVEABLE	Windows NT only: Changes a fixed memory object to a movable memory object if the GMEM_MODIFY flag is also specified.
If this parameter does not specify GMEM_MODIFY, it can be any combination of the following flags:

Flag	Meaning
GMEM_MOVEABLE	If dwBytes is zero, discards a previously movable and discardable memory block. If the lock count of the object is not zero or if the block is not movable and discardable, the function fails.  If dwBytes is nonzero, enables the system to move the reallocated block to a new location without changing the movable or fixed attribute of the memory object. If the object is fixed, the handle returned may be different from the handle specified by the hMem parameter. If the object is movable, the block can be moved without invalidating the handle, even if the object is currently locked by a previous call to the GlobalLock function. To get the new address of the memory block, use GlobalLock.
GMEM_NOCOMPACT	Prevents memory from being compacted or discarded to satisfy the allocation request.
GMEM_ZEROINIT	Causes the additional memory contents to be initialized to zero if the memory object is growing in size.
Return Value

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

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If GlobalReAlloc reallocates a movable object, the return value is the handle of the memory object. To convert the handle to a pointer, use the GlobalLock function.

If GlobalReAlloc reallocates a fixed object, the value of the handle returned is the address of the first byte of the memory block. To access the memory, a process can simply cast the return value to a pointer.

If GlobalReAlloc fails, the original memory is not freed, and the original handle and pointer are still valid.

See Also

GlobalAlloc, GlobalFree, GlobalLock


GlobalSize

The GlobalSize function retrieves the current size, in bytes, of the specified global memory object.

DWORD GlobalSize(

HGLOBAL  hMem	// handle of global memory object
);
Parameters

hMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Value

If the function succeeds, the return value is the size, in bytes, of the specified global memory object.

If the specified handle is not valid or if the object has been discarded, the return value is zero. To get extended error information, call GetLastError.

Remarks

The size of a memory block may be larger than the size requested when the memory was allocated.

To verify that the specified object's memory block has not been discarded, use the GlobalFlags function before calling GlobalSize.

See Also

GlobalAlloc, GlobalFlags, GlobalReAlloc


GlobalUnfix

The GlobalUnfix function is obsolete. It has no meaning in the 32-bit environment.


GlobalUnlock

The GlobalUnlock function decrements the lock count associated with a memory object that was allocated with the GMEM_MOVEABLE flag. This function has no effect on memory objects allocated with the GMEM_FIXED flag.

BOOL GlobalUnlock(

HGLOBAL  hMem	// handle of global memory object
);
Parameters

hMem

Identifies the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function.

Return Value

If the memory object is still locked after decrementing the lock count, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. If GetLastError returns NO_ERROR, the memory object is unlocked.

Remarks

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, the GlobalLock function increments the count by one, and GlobalUnlock decrements the count by one. For each call that a process makes to GlobalLock for an object, it must eventually call GlobalUnlock. Locked memory will not be moved or discarded, unless the memory object is reallocated by using the GlobalReAlloc function. The memory block of a locked memory object remains locked until its lock count is decremented to zero, at which time it can be moved or discarded.

Memory objects allocated with the GMEM_FIXED flag always have a lock count of zero. If the specified memory block is fixed memory, this function returns TRUE.

If the memory object is already unlocked, GlobalUnlock returns FALSE and GetLastError reports ERROR_NOT_LOCKED. Memory objects allocated with the LMEM_FIXED flag always have a lock count of zero and cause the ERROR_NOT_LOCKED error.

A process should not rely on the return value to determine the number of times it must subsequently call GlobalUnlock for a memory object.

See Also

GlobalAlloc, GlobalFlags, GlobalLock, GlobalReAlloc


GlobalUnWire

The GlobalUnWire function is obsolete. Applications that need to lock a global memory object should use the GlobalLock and GlobalUnlock functions.

This function is provided only for compatibility with 16-bit versions of Windows. New Win32-based applications should not use this function.


GlobalWire

The GlobalWire function is obsolete. Win32-based applications should use the GlobalLock and GlobalUnlock functions.


GrayString

The GrayString function draws gray text at the specified location. The function draws the text by copying it into a memory bitmap, graying the bitmap, and then copying the bitmap to the screen. The function grays the text regardless of the selected brush and background. GrayString uses the font currently selected for the specified device context.

If the lpOutputFunc parameter is NULL, GDI uses the TextOut function, and the lpData parameter is assumed to be a pointer to the character string to be output. If the characters to be output cannot be handled by TextOut (for example, the string is stored as a bitmap), the application must supply its own output function.

BOOL GrayString(

HDC  hDC,	// handle of device context
HBRUSH  hBrush,	// handle of brush for graying
GRAYSTRINGPROC  lpOutputFunc,	// address of callback function
LPARAM  lpData,	// 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
);
Parameters

hDC

Identifies the device context.

hBrush

Identifies the brush to be used for graying. If this parameter is NULL, the text is grayed with the same brush that was used to draw window text.

lpOutputFunc

Points to the application-defined function that will draw the string, or, if TextOut is to be used to draw the string, it is a NULL pointer. For details, see the OutputProc callback function.

lpData

Specifies a pointer to data to be passed to the output function. If the lpOutputFunc parameter is NULL, lpData must be a pointer to the string to be output.

nCount

Specifies the number of characters to be output. If the nCount parameter is zero, GrayString calculates the length of the string (assuming lpData is a pointer to the string). If nCount is −1 and the function pointed to by lpOutputFunc returns FALSE, the image is shown but not grayed.

X

Specifies the device x-coordinate of the starting position of the rectangle that encloses the string.

Y

Specifies the device y-coordinate of the starting position of the rectangle that encloses the string.

nWidth

Specifies the width, in device units, of the rectangle that encloses the string. If this parameter is zero, GrayString calculates the width of the area, assuming lpData is a pointer to the string.

nHeight

Specifies the height, in device units, of the rectangle that encloses the string. If this parameter is zero, GrayString calculates the height of the area, assuming lpData is a pointer to the string.

Return Value

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.

Remarks

Without calling GrayString, an application can draw grayed strings on devices that support a solid gray color. The system color COLOR_GRAYTEXT is the solid-gray system color used to draw disabled text. The application can call the GetSysColor function to retrieve the color value of COLOR_GRAYTEXT. If the color is other than zero (black), the application can call the SetTextColor function to set the text color to the color value and then draw the string directly. If the retrieved color is black, the application must call GrayString to gray the text.

See Also

DrawText, GetSysColor, OutputProc, SetTextColor, TabbedTextOut, TextOut


Handler

A Handler function is a function that a service process specifies as the control handling function of a particular service. The function can have any application-defined name.

VOID Handler(

DWORD  fdwControl	// requested control code
);
Parameters

fdwControl

Indicates the requested control code. This value can be one of the standard control codes in the table, or it can be a user-defined control code in the range of 128 to 255, inclusive. For user-defined control codes, the service defines the action associated with the control code.

Value	Meaning
SERVICE_CONTROL_STOP
	Requests the service to stop.
SERVICE_CONTROL_PAUSE
	Requests the service to pause.
SERVICE_CONTROL_CONTINUE
	Requests the paused service to resume.
SERVICE_CONTROL_INTERROGATE
	Requests the service to immediately report its current status information to the service control manager.
SERVICE_CONTROL_SHUTDOWN
	Requests the service to perform cleanup tasks, because the system is shutting down. Due to extremely limited time available for shutdown, this control should only be used by services that absolutely need to shut down —  for instance, when the eventlog service needs to clear a dirty bit in the files that it maintains, or when the server service needs to shut down so that network connections aren't made when the system is in the shutdown state. If the service takes time to shut down, and sends out STOP_PENDING status messages, it is highly recommended that these messages include a waithint so that the service controller will know how long to wait before indicating to the system that service shutdown is complete. The system gives the service control manager a limited amount of time (about 20 seconds) to complete service shutdown, after which time system shutdown proceeds regardless of whether service shutdown is complete.
Return Value

This function does not return a value.

Remarks

When a Win32 service is started, its ServiceMain function should immediately call the RegisterServiceCtrlHandler function to specify a Handler function to handle control requests.

Whenever it receives a control request from the service control manager, the control dispatcher in the main thread of a Win32 service process invokes the control handler function for the specified service. After handling the control request, the control handler must call the SetServiceStatus function to report its current status to the service control manager.

See Also

RegisterServiceCtrlHandler, ServiceMain, SetServiceStatus


HandlerRoutine

A HandlerRoutine function is a function that a console process specifies to handle control signals received by the process. The function can have any name.

BOOL HandlerRoutine(

DWORD  dwCtrlType	//  control signal type
);
Parameters

dwCtrlType

Indicates the type of control signal received by the handler. This value is one of the following:

Signal	Description
CTRL_C_EVENT	A CTRL+C signal was received, either from keyboard input or from a signal generated by the GenerateConsoleCtrlEvent function.
CTRL_BREAK_EVENT	A CTRL+BREAK signal was received, either from keyboard input or from a signal generated by GenerateConsoleCtrlEvent.
CTRL_CLOSE_EVENT	A signal that the system sends to all processes attached to a console when the user closes the console (either by choosing the Close command from the console window's System menu, or by choosing the End Task command from the Task List).
CTRL_LOGOFF_EVENT	A signal that the system sends to all console processes when a user is logging off. This signal does not indicate which user is logging off, so no assumptions can be made.
CTRL_SHUTDOWN_EVENT	A signal that the system sends to all console processes when the system is shutting down.
Return Value

If the function handles the control signal, it should return TRUE. If it returns FALSE, the next handler function in the list of handlers for this process is used.

Remarks

Each console process has its own list of HandlerRoutine functions. Initially, this list contains only a default handler function that calls ExitProcess. A console process adds or removes additional handler functions by calling the SetConsoleCtrlHandler function, which does not affect the list of handler functions for other processes. When a console process receives any of the control signals, its handler functions are called on a last-registered, first-called basis until one of the handlers returns TRUE. If none of the handlers returns TRUE, the default handler is called.

The CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUTDOWN_EVENT signals give the process an opportunity to clean up before termination. A HandlerRoutine called to handle any of these signals can do one of the following after performing any cleanup operations:

•	Call the ExitProcess function to terminate the process.

•	Return FALSE. If none of the registered handler functions returns TRUE, the default handler terminates the process.

•	Return TRUE. In this case, no other handler functions are called, and the system displays a pop-up dialog box that asks the user whether to terminate the process. The system also displays the dialog box if the process does not respond within a certain time-out period (5 seconds for CTRL_CLOSE_EVENT, and 20 seconds for CTRL_LOGOFF_EVENT and CTRL_SHUTDOWN_EVENT).

A process can use the SetProcessShutdownParameters function to prevent the CTRL_LOGOFF_EVENT and CTRL_SHUTDOWN_EVENT dialog box from being displayed. In this case, the system just terminates the process when a HandlerRoutine returns TRUE or when the time-out period elapses.

See Also

ExitProcess, GenerateConsoleCtrlEvent, GetProcessShutdownParameters, SetConsoleCtrlHandler, SetProcessShutdownParameters


HeapAlloc

The HeapAlloc function allocates a block of memory from a heap. The allocated memory is not movable.

LPVOID HeapAlloc(

HANDLE  hHeap,	// handle of the private heap block
DWORD  dwFlags,	// heap allocation control flags
DWORD  dwBytes	// number of bytes to allocate
);
Parameters

hHeap

Specifies the heap from which the memory will be allocated. This parameter is a handle returned by the HeapCreate or GetProcessHeap function.

dwFlags

Specifies several controllable aspects of heap allocation. Specifying any of these flags will override the corresponding flag specified when the heap was created with HeapCreate. You can specify one or more of the following flags:

Flag	Meaning
HEAP_GENERATE_EXCEPTIONS	Specifies that the operating system will raise an exception to indicate a function failure, such as an out-of-memory condition, instead of returning NULL.
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used while this function is accessing the heap. For more information about HEAP_NO_SERIALIZE, see the Remarks section of HeapCreate.
HEAP_ZERO_MEMORY	Specifies that the allocated memory will be initialized to zero.
dwBytes

Specifies the number of bytes to be allocated.

If the heap specified by the hHeap parameter is a "non-growable" heap, dwBytes must be less than 0x7FFF8. You create a non-growable heap by calling the HeapCreate function with a nonzero value.

Return Value

If the function succeeds, the return value is a pointer to the allocated memory block.

If the function fails and you have not specified HEAP_GENERATE_EXCEPTIONS, the return value is NULL.

If the function fails and you have specified HEAP_GENERATE_EXCEPTIONS, the function may generate the following exceptions:

Value	Meaning
STATUS_NO_MEMORY	The allocation attempt failed because of a lack of available memory or heap corruption.
STATUS_ACCESS_VIOLATION	The allocation attempt failed because of heap corruption or improper function parameters.
Note that heap corruption can lead to either exception. It depends upon the nature of the heap corruption.

If the function fails, it does not call SetLastError. An application cannot call GetLastError for extended error information.

Remarks

If HeapAlloc succeeds, it allocates at least the amount of memory requested. If the actual amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual size of the allocated block, use the HeapSize function.

To free a block of memory allocated by HeapAlloc, use the HeapFree function.

Memory allocated by HeapAlloc is not movable. Since the memory is not movable, it is possible for the heap to become fragmented.

Note that if HEAP_ZERO_MEMORY is not specified, the allocated memory will not be initialized to zero.

See Also

GetProcessHeap, HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, HeapSize SetLastError


HeapCompact

The HeapCompact function attempts to compact a specified heap. It compacts the heap by coalescing adjacent free blocks of memory and decommitting large free blocks of memory.

UINT HeapCompact(

HANDLE  hHeap,	// handle to the heap to compact
DWORD  dwFlags	// bit-flags that control heap access during function operation
);
Parameters

hHeap

Handle to the heap that the function will attempt to compact.

dwFlags

A set of bit flags that control heap access during function operation. The following bit flag has meaning:

Value	Meaning
HEAP_NO_SERIALIZE	If this flag is set, heap access is not serialized while the HeapCompact function accesses the heap; heap access is not mutually exclusive. It is safe to set this flag only in a limited set of specific situations. For a discussion of those situations and heap serialization in general, see the Remarks section of  HeapCreate .  If this flag is clear, heap access is serialized while HeapCompact accesses the heap; heap access is mutually exclusive. This is the safe and simple default condition.
Return Value

If the function succeeds, the return value is the size, in bytes, of the largest committed free block in the heap. This is an unsigned integer value.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

In the unlikely case that there is absolutely no space available in the heap, the function return value is zero, and GetLastError returns the value NO_ERROR.

Remarks

There is no guarantee that an application can successfully allocate a memory block of the size returned by HeapCompact. Other threads or the commit threshold might prevent such an allocation.

See Also

HeapCreate, HeapValidate


HeapCreate

The HeapCreate function creates a heap object that can be used by the calling process. The function reserves a contiguous block in the virtual address space of the process and allocates physical storage for a specified initial portion of this block.

HANDLE HeapCreate(

DWORD  flOptions,	// heap allocation flag
DWORD  dwInitialSize,	// initial heap size
DWORD  dwMaximumSize	// maximum heap size
);
Parameters

flOptions

Specifies optional attributes for the new heap. These flags will affect subsequent access to the new heap through calls to the heap functions (HeapAlloc, HeapFree, HeapReAlloc, and HeapSize). You can specify one or more of the following flags:

Flag	Meaning
HEAP_GENERATE_EXCEPTIONS	Specifies that the system will raise an exception to indicate a function failure, such as an out-of-memory condition, instead of returning NULL.
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used when the heap functions allocate and free memory from this heap. The default, occurring when the HEAP_NO_SERIALIZE flag is not specified, is to serialize access to the heap. Serialization of heap access allows two or more threads to simultaneously allocate and free memory from the same heap.
dwInitialSize

Specifies the initial size, in bytes, of the heap. This value determines the initial amount of physical storage that is allocated for the heap. The value is rounded up to the next page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function.

dwMaximumSize

If dwMaximumSize is a nonzero value, it specifies the maximum size, in bytes, of the heap. The HeapCreate function rounds dwMaximumSize up to the next page boundary, and then reserves a block of that size in the process's virtual address space for the heap. If allocation requests made by the HeapAlloc or HeapReAlloc functions exceed the initial amount of physical storage specified by dwInitialSize, the system allocates additional pages of physical storage for the heap, up to the heap's maximum size.

In addition, if dwMaximumSize is nonzero, the heap cannot grow, and an absolute limitation arises: the maximum size of a memory block in the heap is a bit less than 0x7FFF8 bytes. Requests to allocate larger blocks will fail, even if the maximum size of the heap is large enough to contain the block.

If dwMaximumSize is zero, it specifies that the heap is growable. The heap's size is limited only by available memory. Requests to allocate blocks larger than 0x7FFF8 bytes do not automatically fail; the system calls VirtualAlloc to obtain the memory needed for such large blocks. Applications that need to allocate large memory blocks should set dwMaximumSize to zero.

Return Value

If the function succeeds, the return value is a handle of the newly created heap.

If the function fails, the return value is is NULL. To get extended error information, call GetLastError.

Remarks

The HeapCreate function creates a private heap object from which the calling process can allocate memory blocks by using the HeapAlloc function. The initial size determines the number of committed pages that are initially allocated for the heap. The maximum size determines the total number of reserved pages. These pages create a contiguous block in the process's virtual address space into which the heap can grow. If requests by HeapAlloc exceed the current size of committed pages, additional pages are automatically committed from this reserved space, assuming that the physical storage is available.

The memory of a private heap object is accessible only to the process that created it. If a dynamic-link library (DLL) creates a private heap, the heap is created in the address space of the process that called the DLL, and it is accessible only to that process.

The system uses memory from the private heap to store heap support structures, so not all of the specified heap size is available to the process. For example, if the HeapAlloc function requests 64 kilobytes (K) from a heap with a maximum size of 64K, the request may fail because of system overhead.

If the HEAP_NO_SERIALIZE flag is not specified (the simple default), the heap will serialize access within the calling process. Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap.

Setting the HEAP_NO_SERIALIZE flag eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE flag can, therefore, be safely used only in the following situations:

•	The process has only one thread.

•	The process has multiple threads, but only one thread calls the heap functions for a specific heap.

•	The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.

See Also

GetProcessHeap, GetProcessHeaps, GetSystemInfo, HeapAlloc, HeapDestroy, HeapFree, HeapReAlloc, HeapSize, HeapValidate, VirtualAlloc,


HeapDestroy

The HeapDestroy function destroys the specified heap object. HeapDestroy decommits and releases all the pages of a private heap object, and it invalidates the handle of the heap.

BOOL HeapDestroy(

HANDLE  hHeap	// handle of heap
);
Parameters

hHeap

Specifies the heap to be destroyed. This parameter should be a heap handle returned by the HeapCreate function. A heap handle returned by the GetProcessHeap function should not be used.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Processes can call HeapDestroy without first calling the HeapFree function to free memory allocated from the heap.

See Also

GetProcessHeap, HeapAlloc, HeapCreate, HeapFree, HeapReAlloc, HeapSize


HeapFree

The HeapFree function frees a memory block allocated from a heap by the HeapAlloc or HeapReAlloc function.

BOOL HeapFree(

HANDLE  hHeap,	// handle of the heap
DWORD  dwFlags,	// heap freeing flags
LPVOID  lpMem	// address of the memory to free
);
Parameters

hHeap

Specifies the heap whose memory block the function frees. This parameter is a handle returned by the HeapCreate or GetProcessHeap function.

dwFlags

Specifies several controllable aspects of freeing a memory block. Only one flag is currently defined; however, all other flag values are reserved for future use. Specifying this flag will override the corresponding flag specified in the flOptions parameter when the heap was created by using the HeapCreate function:

Flag	Meaning
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used while the function is accessing the heap. For more information about HEAP_NO_SERIALIZE, see the Remarks for the HeapCreate function.
lpMem

Points to the memory block to free. This pointer is returned by the HeapAlloc or HeapReAlloc function.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, it returns FALSE and calls SetLastError. An application can call GetLastError for extended error information.

See Also

GetProcessHeap, HeapAlloc, HeapCreate, HeapDestroy, HeapReAlloc, HeapSize, SetLastError


HeapLock

The HeapLock function attempts to acquire the critical section object, or lock, that is associated with a specified heap.

If the function succeeds, the calling thread owns the heap lock. Only the calling thread will be able to allocate or release memory from the heap. The execution of any other thread of the calling process will be blocked if that thread attempts to allocate or release memory from the heap. Such threads will remain blocked until the thread that owns the heap lock calls the HeapUnlock function.

BOOL HeapLock(

HANDLE  hHeap	// handle to the heap to lock for exclusive thread access
);
Parameters

hHeap

Handle to the heap to lock for exclusive access by the calling thread.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The HeapLock function is primarily useful for preventing the allocation and release of heap memory by other threads while the calling thread uses the HeapWalk function.

Each call to HeapLock must be matched by a corresponding call to the HeapUnlock function. Failure to call HeapUnlock will block the execution of any other threads of the calling process that attempt to access the heap.

See Also

HeapUnlock, HeapWalk


HeapReAlloc

The HeapReAlloc function reallocates a block of memory from a heap. This function enables you to resize a memory block and change other memory block properties. The allocated memory is not movable.

LPVOID HeapReAlloc(

HANDLE  hHeap,	// handle of a heap block
DWORD  dwFlags,	// heap reallocation flags
LPVOID  lpMem,	// address of the memory to reallocate
DWORD  dwBytes	// number of bytes to reallocate
);
Parameters

hHeap

Specifies the heap from which the memory will be reallocated. This is a handle returned by the HeapCreate or GetProcessHeap function.

dwFlags

Specifies several controllable aspects of heap reallocation. Specifying any of these flags will override the corresponding flag specified in the flOptions parameter when the heap was created by using the HeapCreate function. You can specify one or more of the following flags:

Flag	Meaning
HEAP_GENERATE_EXCEPTIONS	Specifies that the operating-system will raise an exception to indicate a function failure, such as an out-of-memory condition, instead of returning NULL.
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used while this function is accessing the heap. For more information about HEAP_NO_SERIALIZE, see the Remarks section of HeapCreate.
HEAP_REALLOC_IN_PLACE_ONLY	Specifies that there can be no movement when reallocating a memory block to a larger size. If this flag is not specified and the reallocation request is for a larger size, the function may move the block to a new location. If this flag is specified and the block cannot be enlarged without moving, the function will fail, leaving the original memory block unchanged.
HEAP_ZERO_MEMORY	If the reallocation request is for a larger size, this flag specifies that the additional region of memory beyond the original size will be initialized to zero. The contents of the memory block up to its original size are unaffected.
lpMem

Points to the block of memory that the function reallocates. This pointer is returned by an earlier call to the HeapAlloc or HeapReAlloc function.

dwBytes

Specifies the new size of the memory block, in bytes. A memory block's size can be increased or decreased by using this function.

If the heap specified by the hHeap parameter is a "non-growable" heap, dwBytes must be less than 0x7FFF8. You create a non-growable heap by calling the HeapCreate function with a nonzero value.

Return Value

If the function succeeds, the return value is a pointer to the reallocated memory block.

If the function fails and you have not specified HEAP_GENERATE_EXCEPTIONS, the return value is NULL.

If the function fails and you have specified HEAP_GENERATE_EXCEPTIONS, the function may generate the following exceptions:

Value	Meaning
STATUS_NO_MEMORY	The reallocation attempt failed for lack of available memory.
STATUS_ACCESS_VIOLATION	The reallocation attempt failed because of heap corruption or improper function parameters.
If the function fails, it calls SetLastError. An application can call GetLastError for extended error information.

Remarks

If HeapReAlloc succeeds, it allocates at least the amount of memory requested. If the actual amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual size of the reallocated block, use the HeapSize function.

To free a block of memory allocated by HeapReAlloc, use the HeapFree function.

See Also

GetProcessHeap, HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapSize, SetLastError


HeapSize

The HeapSize function returns the size, in bytes, of a memory block allocated from a heap by the HeapAlloc or HeapReAlloc function.

DWORD HeapSize(

HANDLE  hHeap,	// handle of the heap
DWORD dwFlags,	// heap size control flags
LPCVOID  lpMem	// address of memory to return size for
);
Parameters

hHeap

Specifies the heap in which the memory block resides. This handle is returned by the HeapCreate or GetProcessHeap function.

dwFlags

Specifies several controllable aspects of accessing the memory block. Only one flag is currently defined; however, all other flag values are reserved for future use. Specifying this flag will override the corresponding flag specified in the flOptions parameter when the heap was created by using the HeapCreate function:

Value	Meaning
HEAP_NO_SERIALIZE	Specifies that mutual exclusion will not be used while the function is accessing the heap. For more information about HEAP_NO_SERIALIZE, see the Remarks for HeapCreate.
lpMem

Points to the memory block whose size the function will obtain. This is a pointer returned by the HeapAlloc or HeapReAlloc function.

Return Value

If the function succeeds, the return value is the size, in bytes, of the allocated memory block.

If the function fails, the return value is 0xFFFFFFFF. The function does not call SetLastError. An application cannot call GetLastError for extended error information.

See Also

GetProcessHeap, HeapAlloc, HeapCreate, HeapDestroy, HeapFree, HeapReAlloc, SetLastError


HeapUnlock

The HeapUnlock function releases ownership of the critical section object, or lock, that is associated with a specified heap. The HeapUnlock function reverses the action of the HeapLock function.

BOOL HeapUnlock(

HANDLE  hHeap	// handle to the heap to unlock
);
Parameters

hHeap

Handle to the heap to unlock.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The HeapLock function is primarily useful for preventing the allocation and release of heap memory by other threads while the calling thread uses the HeapWalk function. The HeapUnlock function is the inverse of HeapLock.

Each call to HeapLock must be matched by a corresponding call to the HeapUnlock function. Failure to call HeapUnlock will block the execution of any other threads of the calling process that attempt to access the heap.

See Also

HeapLock, HeapWalk


HeapValidate

The HeapValidate function attempts to validate a specified heap. The function scans all the memory blocks in the heap, and verifies that the heap control structures maintained by the operating system's heap manager are in a consistent state. You can also use the HeapValidate function to validate a single memory block within a specified heap, without checking the validity of the entire heap.

BOOL HeapValidate(

HANDLE  hHeap,	// handle to the heap of interest
DWORD  dwFlags,	// bit flags that control heap access during function operation
LPCVOID  lpMem	// optional pointer to individual memory block to validate
);
Parameters

hHeap

Handle to the heap of interest. The HeapValidate function attempts to validate this heap, or a single memory block within this heap.

dwFlags

A set of bit flags that control heap access during function operation. The following bit flag has meaning:

Value	Meaning
HEAP_NO_SERIALIZE	If this flag is set, heap access is not serialized while the HeapValidate function accesses the heap; heap access is not mutually exclusive. It is safe to set this flag only in a limited set of specific situations. For a discussion of those situations and heap serialization in general, see the Remarks section of HeapCreate .  If this flag is clear, heap access is serialized while HeapValidate accesses the heap; heap access is mutually exclusive. This is the safe and simple default condition.
lpMem

Points to a memory block within the specified heap. This parameter may be NULL.

If this parameter is NULL, the function attempts to validate the entire heap specified by hHeap.

If this parameter is not NULL, the function attempts to validate the memory block pointed to by lpMem. It does not attempt to validate the rest of the heap.

Return Value

If the specified heap or memory block is valid, the return value is TRUE.

If the specified heap or memory block is invalid, the return value is FALSE. On a system set up for debugging, the HeapValidate function then displays debugging messages that describe the part of the heap or memory block that is invalid, and stops at a hard-coded breakpoint so that you can examine the system to determine the source of the invalidity. The HeapValidate function does not set the thread's last error value.

Remarks

There are heap control structures for each memory block in a heap, and for the heap as a whole. When you use the HeapValidate function to validate a complete heap, it checks all of these control structures for consistency. When you use HeapValidate to validate a single memory block within a heap, it checks only the control structures pertaining to that element.

See Also

HeapCreate, HeapWalk


HeapWalk

The HeapWalk function enumerates the memory blocks in a specified heap.

BOOL HeapWalk(

HANDLE  hHeap,	// handle to the heap to enumerate
LPPROCESS_HEAP_ENTRY  lpEntry	// points to structure that maintains enumeration state information
);
Parameters

hHeap

Handle to the heap whose memory blocks you wish to enumerate.

dwFlags

Points to a PROCESS_HEAP_ENTRY structure that maintains state informationfor a particular heap enumeration.

If the HeapWalk function succeeds, returning the value TRUE, this structure's members contain information about the next memory block in the heap.

To initiate a heap enumeration, set the lpData field of the PROCESS_HEAP_ENTRY structure to NULL. To continue a particular heap enumeration, call the HeapWalk function repeatedly, with no changes to hHeap, lpEntry, or any of the members of the PROCESS_HEAP_ENTRY structure.

Return Value

If the function succeeds, the return value is TRUE.

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

If the heap enumeration terminates successfully by reaching the end of the heap, the function returns FALSE, and GetLastError returns the error code ERROR_NO_MORE_ITEMS.

Remarks

To initiate a heap enumeration, call HeapWalk with the lpData field of the PROCESS_HEAP_ENTRY structure pointed to by lpEntry set to NULL.

To continue a heap enumeration, call HeapWalk with the same hHeap and lpEntry values, and with the PROCESS_HEAP_ENTRY structure unchanged from the preceding call to HeapWalk. Repeat this process until you have no need for further enumeration, or until the function returns FALSE and GetLastError returns ERROR_NO_MORE_ITEMS, indicating that all of the heap's memory blocks have been enumerated.

No special call of HeapWalk is needed to terminate the heap enumeration, since no enumeration state data is maintained outside the contents of the PROCESS_HEAP_ENTRY structure.

HeapWalk can fail in a multithreaded application if the heap is not locked during the heap enumeration. Use the HeapLock and HeapUnlock functions to control heap locking during heap enumeration.

See Also

HeapLock, HeapUnlock, HeapValidate, PROCESS_HEAP_ENTRY


HideCaret

The HideCaret function removes the caret from the screen. Hiding a caret does not destroy its current shape or invalidate the insertion point.

BOOL HideCaret(

HWND  hWnd	// handle of window with caret
);
Parameters

hWnd

Identifies the window that owns the caret. If this parameter is NULL, HideCaret searches the current task for the window that owns the caret.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

HideCaret hides the caret only if the specified window owns the caret. If the specified window does not own the caret, HideCaret does nothing and returns FALSE.

Hiding is cumulative. If your application calls HideCaret five times in a row, it must also call ShowCaret five times before the caret is displayed.

See Also

CreateCaret, DestroyCaret, GetCaretPos, SetCaretPos, ShowCaret


HiliteMenuItem

The HiliteMenuItem function highlights or removes the highlighting from an item in a menu bar.

BOOL HiliteMenuItem(

HWND  hwnd,	// handle of window with menu
HMENU  hmenu,	// handle of menu
UINT  uItemHilite,	// menu item to highlight or unhighlight
UINT  uHilite	// highlight flags
);
Parameters

hwnd

Identifies the window that contains the menu.

hmenu

Identifies the menu bar that contains the item to be highlighted.

uItemHilite

Specifies the menu item to be highlighted. This parameter is either the identifier of the menu item or the offset of the menu item in the menu bar, depending on the value of the uHilite parameter.

uHilite

Specifies flags that control the interpretation of the uItemHilite parameter and indicates whether the menu item is highlighted. This parameter must be a combination of either MF_BYCOMMAND or MF_BYPOSITION and MF_HILITE or MF_UNHILITE.

Value	Meaning
MF_BYCOMMAND	Indicates that uItemHilite gives the identifier of the menu item.
MF_BYPOSITION	Indicates that uItemHilite gives the zero-based relative position of the menu item.
MF_HILITE	Highlights the menu item. If this flag is not specified, the highlighting is removed from the item.
MF_UNHILITE	Removes highlighting from the menu item.
Return Value

If the menu item is set to the specified highlight state, the return value is TRUE; otherwise, it is FALSE.

Remarks

The MF_HILITE and MF_UNHILITE flags can be used only with the HiliteMenuItem function; they cannot be used with the ModifyMenu function.

See Also

ModifyMenu


htonl

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

This function takes a 32-bit number in host byte order and returns a 32-bit number in network byte order.

u_long htonl (

u_long hostlong
);
Parameters

hostlong

A 32-bit number in host byte order.

Return Value

The htonl function returns the value in network byte order.

See Also

htons, ntohl, ntohs


htons

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

u_short htons (

u_short hostshort
);
Parameters

hostshort

A 16-bit number in host byte order.

Return Value

The htons function returns the value in network byte order.

Remarks

This function takes a 16-bit number in host byte order and returns a 16-bit number in network byte order.

See Also

htonl, ntohl, ntohs


ImageList_Add  (preliminaryWindows NT)
ImageList_Add  (preliminary−Windows NT)

The ImageList_Add function adds an image or images to an image list.

int WINAPI ImageList_Add(

HIMAGELIST  himl,
HBITMAP  hbmImage,
HBITMAP  hbmMask
);
Parameters

himl

Handle to the image list.

hbmImage

Handle to the bitmap that contains the image or images. The number of images is inferred from the width of the bitmap.

hbmMask

Handle to the bitmap that contains the mask. If no mask is used with the image list, this parameter is ignored.

Return Value

If the function succeeds, the return value is the index of the first new image.

If the function fails, the return value is − 1.

Remarks

The ImageList_Add function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and hbmMask after the function returns.

See Also

DeleteObject


ImageList_AddIcon  (preliminaryWindows NT)
ImageList_AddIcon  (preliminary−Windows NT)

The ImageList_AddIcon function adds an icon or cursor to an image list.

int  WINAPI ImageList_AddIcon(

HIMAGELIST  himl,	//
HICON hicon	//
);
Parameters

himl

Handle to the image list. If this parameter identifies a masked image list, the function copies both the image and mask bitmaps of the icon or cursor. If this parameter identifies a nonmasked image list, the function copies only the image bitmap.

hicon

Handle to the icon or cursor that contains the bitmap and mask for the new image.

Return Value

If the function succeeds, the return value is the index of the new image.

If the function fails, the return value is  − 1.

Remarks

Because the system does not save hicon, you can destroy it after the function returns if the icon or cursor was created by the CreateIcon function. You do not need to destroy hicon if it was loaded by the LoadIcon function; the system automatically frees an icon resource when it is no longer needed.

See Also

CreateIcon, LoadIcon


ImageList_AddMasked  (preliminaryWindows NT)
ImageList_AddMasked  (preliminary−Windows NT)

The ImageList_AddMasked function adds an image or images to an image list, generating a mask from the specified bitmap.

int WINAPI ImageList_AddMasked(

HIMAGELIST  himl,
HBITMAP  hbmImage,
COLORREF  crMask
);
Parameters

himl

Handle to the image list.

hbmImage

Handle to the bitmap that contains one or more images. The number of images is inferred from the width of the bitmap.

crMask

Color used to generate the mask. Each pixel of this color in the specified bitmap is changed to black, and the corresponding bit in the mask is set to one.

Return Value

If the function succeeds, the return value is the index of the first new image.

If the function fails, the return value is  − 1.

Remarks

The ImageList_AddMasked function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and crMask after the function returns.

See Also

DeleteObject


ImageList_BeginDrag  (preliminaryWindows NT)
ImageList_BeginDrag  (preliminary−Windows NT)

The ImageList_BeginDrag function begins dragging an image.

BOOL WINAPI ImageList_BeginDrag(

HIMAGELIST  himlTrack,
int  iTrack,
int  dxHotspot,
int  dyHotspot
);
Parameters

himlTrack

Handle to the image list.

iTrack

Index of the image to drag.

dxHotspot and dyHotspot

Location of the drag position relative to the upper-left corner of the image.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

This function creates a temporary image list that is used for dragging. In response to subsequent WM_MOUSEMOVE messages, you can move the drag image by using the ImageList_DragMove function. To end the drag operation, you can use the ImageList_EndDrag function.

See Also

ImageList_DragMove, ImageList_EndDrag, WM_MOUSEMOVE


ImageList_Create  (preliminaryWindows NT)
ImageList_Create  (preliminary−Windows NT)

The ImageList_Create function creates a new image list.

HIMAGELIST WINAPI ImageList_Create(

int  cx,
int  cy,
UINT  flags,
int  cInitial,
int  cGrow
);
Parameters

cx

Specifies the width, in pixels, of each image.

cy

Specifies the height, in pixels, of each image.

flags

Flags specifying the type of image list to create. This parameter can be a combination of the following values:

Value	Meaning
ILC_COLOR4	Uses 4-bit device-independent bitmap (DIB) sections.
ILC_COLOR8	Uses 8-bit DIB sections.
ILC_COLOR16	Uses 16-bit DIB sections.
ILC_COLOR24	Uses 24-bit DIB sections.
ILC_COLOR32	Uses 32-bit DIB sections.
ILC_COLORDDB	Uses device-dependent bitmaps.
ILC_MASK	Uses a mask. The image list contains two bitmaps, one of which is a monochrome bitmap used as a mask. If this value is not included, the image list contains only one bitmap.
ILC_PALETTE	Uses a color palette with the image list.
cInitial

Number of images that the image list initially contains.

cGrow

Amount of images by which the image list can grow when the system needs to resize the list to make room for new images. This parameter represents the number of new images that the resized image list can contain.

Return Value

If the function succeeds, the return value is the handle to the image list.

If the function fails, the return value NULL.


ImageList_Destroy  (preliminaryWindows NT)
ImageList_Destroy  (preliminary−Windows NT)

The ImageList_Destroy function destroys an image list.

BOOL WINAPI ImageList_Destroy(

HIMAGELIST  himl
);
Parameters

himl

Handle to the image list to destroy.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImageList_DragEnter  (preliminaryWindows NT)
ImageList_DragEnter  (preliminary−Windows NT)

The ImageList_DragEnter function locks updates to the specified window during a drag operation and displays the drag image at the specified position within the window.

BOOL WINAPI ImageList_DragEnter(

HWND  hwndLock,
int  x,
int  y
);
Parameters

hwndLock

Handle to the window that owns the drag image.

x

Specifies the x-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.

y

Specifies the y-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

To begin a drag operation, use the ImageList_BeginDrag function.

See Also

ImageList_BeginDrag


ImageList_DragLeave  (preliminaryWindows NT)
ImageList_DragLeave  (preliminary−Windows NT)

The ImageList_DragLeave function unlocks the specified window and hides the drag image, allowing the window to be updated.

BOOL WINAPI ImageList_DragLeave(

HWND  hwndLock	//
);
Parameters

hwndLock

Handle to the window that owns the drag image.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImageList_DragMove  (preliminaryWindows NT)
ImageList_DragMove  (preliminary−Windows NT)

The ImageList_DragMove function moves the image that is being dragged during a drag-and-drop operation. This function is typically called in response to a WM_MOUSEMOVE message.

BOOL WINAPI ImageList_DragMove(

int  x,	//
int  y	//
);
Parameters

x and y

New drag position.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

To begin a drag operation, use the ImageList_BeginDrag function.

See Also

ImageList_BeginDrag, WM_MOUSEMOVE


ImageList_DragShowNolock  (preliminaryWindows NT)
ImageList_DragShowNolock  (preliminary−Windows NT)

The ImageList_DragShowNolock function shows or hides the image being dragged.

BOOL WINAPI ImageList_DragShowNolock(

BOOL  fShow	//
);
Parameters

fShow

Value specifying whether to show or hide the image being dragged. Specify TRUE to show the image, FALSE to hide the image.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImageList_Draw  (preliminaryWindows NT)
ImageList_Draw  (preliminary−Windows NT)

The ImageList_Draw function draws an image list item in the specified device context.

BOOL WINAPI ImageList_Draw(

HIMAGELIST  himl,
int  i,
HDC  hdcDst,
int  x,
int  y,
UINT  fStyle
);
Parameters

himl and i

Handle to the image list, and the index of the image to draw.

hdcDst

Handle to the destination device context.

x

Specifies the x-coordinate at which to draw within the specified device context.

y

Specifies the y-coordinate at which to draw within the specified device context.

fStyle

Flag specifying the drawing style. This parameter can be one or more of the following values:

Value	Meaning
ILD_BLEND25	Draws the image, blending 25 percent with the system highlight color. This value has no effect if the image list does not contain a mask.
ILD_BLEND50	Draws the image, blending 50 percent with the system highlight color. This value has no effect if the image list does not contain a mask.
ILD_FOCUS	Same as ILD_BLEND25.
ILD_MASK	Draws the mask.
ILD_NORMAL	Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask.
ILD_TRANSPARENT	Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask.
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImageList_DrawEx  (preliminaryWindows NT)
ImageList_DrawEx  (preliminary−Windows NT)

The ImageList_DrawEx function draws an image list item in the specified device context. The function uses the specified drawing style and blends the image with the specified color.

BOOL WINAPI ImageList_DrawEx(

HIMAGELIST  himl,
int  i,
int  x,
int  y,
int  dx,
int  dy,
COLORREF  rgbBk,
COLORREF  rgbFg,
UINT  fStyle
);
Parameters

himl

Handle to the image list

i

Index of the image to draw.

hdcDst

Handle to the destination device context.

x

Specifies the x-coordinate at which to draw within the specified device context.

y

Specifies the y-coordinate at which to draw within the specified device context.

dx and dy

Portion of the image to draw, relative to the upper-left corner of the image. If these parameters are zero, the function draws the entire image. The function does not ensure that the parameters are valid.

rgbBk

Background color of the image. This parameter can be an application-defined RGB value or one of the following values:

Value	Meaning
CLR_NONE	No background color. The image is drawn transparently.
CLR_DEFAULT	Default background color. The image is drawn using the background color of the image list.
This parameter is used only if the image list identified by himl was created with the ILC_MASK value.

rgbFg

Foreground color of the image. This parameter can be an application-defined RGB value or one of the following values:

Value	Meaning
CLR_NONE	No blend color. The image is blended with the color of the destination device context.
CLR_DEFAULT	Default foreground color. The image is drawn using the system highlight color as the foreground color.
This parameter is used only if fStyle includes the ILD_BLEND25 or ILD_BLEND50 value.

fStyle

Flag specifying the drawing style. This parameter can be one or more of the following values:

Value	Meaning
ILD_BLEND25	Draws the image, blending 25 percent with the blend color specified by rgbFG. This value has no effect if the image list does not contain a mask.
ILD_BLEND50	Draws the image, blending 50 percent with the blend color specified by rgbFG. This value has no effect if the image list does not contain a mask.
ILD_FOCUS	Same as ILD_BLEND25.
ILD_MASK	Draws the mask.
ILD_NORMAL	Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask.
ILD_TRANSPARENT	Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask.
See Also

RGB


ImageList_EndDrag  (preliminaryWindows NT)
ImageList_EndDrag  (preliminary−Windows NT)

The ImageList_EndDrag function ends a drag operation.

BOOL WINAPI ImageList_EndDrag(VOID)

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImageList_ExtractIcon  (preliminaryWindows NT)
ImageList_ExtractIcon  (preliminary−Windows NT)

The ImageList_ExtractIcon function creates an icon or cursor based on an image and mask in an image list. ImageList_ExtractIcon is a macro that calls the ImageList_GetIcon function.

HICON WINAPI ImageList_ExtractIcon(

HINSTANCE  hi,
HIMAGELIST  himl,
int  i
);
Parameters

hi

Ignored; set to zero.

himl

Handle to the image list.

i

Index of the image.

Return Value

If the function succeeds, the return value is the handle of the icon or cursor.

If the function fails, the return value is NULL.

See Also

ImageList_GetIcon


ImageList_GetBkColor  (preliminaryWindows NT)
ImageList_GetBkColor  (preliminary−Windows NT)

The ImageList_GetBkColor function retrieves the current background color for an image list.

COLORREF WINAPI ImageList_GetBkColor(

HIMAGELIST  himl
);
Parameters

himl

Handle to the image list.

Return Value

The return value is the background color.


ImageList_GetDragImage  (preliminaryWindows NT)
ImageList_GetDragImage  (preliminary−Windows NT)

The ImageList_GetDragImage function retrieves the temporary image list that is used for the drag image. The function also retrieves the current drag position, and the offset of the drag image relative to the drag position.

HIMAGELIST WINAPI ImageList_GetDragImage(

POINT FAR* ppt,
POINT FAR* pptHotspot
);
Parameters

ppt

Pointer to a POINT structure that receives the current drag position. Can be NULL.

pptHotSpot

Pointer to a POINT structure that receives the offset of the drag image relative to the drag position. Can be NULL.

Return Value

If the function succeeds, the return value is the handle of the image list.

If the function fails, the return value is NULL.

Remarks

The temporary image list is destroyed when the ImageList_EndDrag function is called. To begin a drag operation, use the ImageList_BeginDrag function.

See Also

ImageList_BeginDrag, ImageList_EndDrag, POINT


ImageList_GetIcon  (preliminaryWindows NT)
ImageList_GetIcon  (preliminary−Windows NT)

The ImageList_GetIcon function creates an icon or cursor based on an image and mask in an image list.

HICON WINAPI ImageList_GetIcon(

HIMAGELIST himl,	//
int  i,	//
UINT  flags	//
);
Parameters

himl

Handle to the image list.

i

Index of the image.

flags

Combination of flags that specify the drawing style. For a list of values, see the description of the ImageList_Draw function.

Return Value

If the function succeeds, the return value is the handle of the icon or cursor.

If the function fails, the return value is NULL.

See Also

ImageList_Draw


ImageList_GetIconSize  (preliminaryWindows NT)
ImageList_GetIconSize  (preliminary−Windows NT)

The ImageList_GetIconSize function retrieves the dimensions of images in an image list. All images in an image list have the same dimensions.

BOOL WINAPI ImageList_GetIconSize(

HIMAGELIST  himl,
int FAR  * cx,
int FAR  * cy
);
Parameters

himl

Handle to the image list.

cx

Pointer to integer variable that receives the width, in pixels, of each image.

cy

Pointer to integer variable that receives the height, in pixels, of each image.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImageList_GetImageCount  (preliminaryWindows NT)
ImageList_GetImageCount  (preliminary−Windows NT)

The ImageList_GetImageCount function retrieves the number of images in an image list.

int WINAPI ImageList_GetImageCount(;

HIMAGELIST  himl
);
Parameters

himl

Handle to the image list.

Return Value

The ImageList_GetImageCount function returns the number of images.


ImageList_GetImageInfo  (preliminaryWindows NT)
ImageList_GetImageInfo  (preliminary−Windows NT)

The ImageList_GetImageInfo function retrieves information about an image.

BOOL WINAPI ImageList_GetImageInfo(

HIMAGELIST  himl,
int  i,
IMAGEINFO FAR*  pImageInfo
);
Parameters

himl

Handle to the image list.

i

Index of the image.

pImageInfo

Pointer to an IMAGEINFO structure that receives information about the image. The information in this structure can be used to directly manipulate the bitmaps for the image.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

IMAGEINFO


ImageList_LoadBitmap  (preliminaryWindows NT)
ImageList_LoadBitmap  (preliminary−Windows NT)

The ImageList_LoadBitmap function creates an image list from the specified bitmap resource. ImageList_LoadBitmap is a macro that calls the ImageList_LoadImage function.

HIMAGELIST WINAPI ImageList_LoadBitmap(

HINSTANCE  hi,
LPCSTR  lpbmp,
int  cx,
int  cGrow,
COLORREF  crMask
);
Parameters

hi

Handle to the instance that contains the bitmap resource.

lpbmp

Name of the resource.

cx

Width of each image. The height of each image and the initial number of images are inferred by the dimensions of the specified bitmap.

cGrow

Amount of images by which the image list can grow when the system needs to resize the list to make room for new images. This parameter represents the number of new images that the resized image list can contain.

crMask

Color used to generate a mask. Each pixel of this color in the specified bitmap is changed to black, and the corresponding bit in the mask is set to one. If this parameter is the CLR_NONE value, no mask is generated.

Return Value

If the function succeeds, the return value is the image list.

If the function fails, the return value is NULL.

See Also

ImageList_LoadImage


ImageList_LoadImage  (preliminaryWindows NT)
ImageList_LoadImage  (preliminary−Windows NT)

The ImageList_LoadImage function creates an image list from the specified bitmap, cursor, or icon resource.

HIMAGELIST WINAPI ImageList_LoadImage(

HINSTANCE  hi,
LPCSTR  lpbmp,
int  cx,
int  cGrow,
COLORREF  crMask,
UINT  uType,
UINT   uFlags
);
Parameters

hi

Handle to the instance that contains the resource.

If the hi parameter is zero, the low-order word of this parameter must be the identifier of the OEM image to load. The OEM image identifiers are defined in WINUSER.H. Following are the identifier prefixes and their meanings:

Prefix	Meaning
OBM_	OEM bitmaps
OIC_	OEM icons
OCR_	OEM cursors
lpbmp

Pointer to a null-terminated string that contains the name of the image to load.

If the uFlags parameter specifies the LR_LOADFROMFILE value, the lpbmp parameter must be the name of the file that contains the image.

cx

Width of each image. The height of each image and the initial number of images are inferred by the dimensions of the specified resource.

cGrow

Amount of images by which the image list can grow when the system needs to resize the list to make room for new images. This parameter represents the number of new images that the resized image list can contain.

crMask

Color used to generate a mask. Each pixel of this color in the specified bitmap, cursor, or icon is changed to black, and the corresponding bit in the mask is set to 1. If this parameter is the CLR_NONE value, no mask is generated.

uType

Flag that specifies the type of image to load. This parameter can be one of the following values:

Value	Meaning
IMAGE_BITMAP	Loads a bitmap.
IMAGE_CURSOR	Loads a cursor.
IMAGE_ICON	Loads an icon.
uFlags

Flags that specify how to load the image. This parameter can be a combination of the following values:

Value	Meaning
LR_DEFAULTCOLOR	Uses the color format of the display.
LR_LOADDEFAULTSIZE	Uses the width or height specified by the system metric values for cursors and icons if the cx parameter is set to zero. If this value is not specified and cx is set to zero, the function sets the size to that specified in the resource. If the resource contains multiple images, the function sets the size to that of the first image.
LR_LOADFROMFILE	Loads the image from the file specified by the lpbmp parameter.
LR_LOADMAP3DCOLORS	Searches the color table for the image and replaces the following shades of gray with the corresponding three-dimensional color:
Dk Gray, RGB(128, 128, 128)	COLOR_3DSHADOW
Gray,  RGB(192, 192, 192)	COLOR_3DFACE
Lt Gray,  RGB(223, 223, 223)	COLOR_3DLIGHT
LR_LOADTRANSPARENT	Retrieves the color value of the first pixel in the image and replaces the corresponding entry in the color table with the default window color (the COLOR_WINDOW display color). All pixels in the image that use that entry become the default window value color. This value applies only to images that have corresponding color tables.
LR_MONOCHROME	Loads the image in black and white.
LR_SHARED	Shares the image handle if the image is loaded multiple times. Do not use this value for images that have nontraditional sizes that might change after loading or for images that are loaded from a file.
Return Value

If the function succeeds, the return value is the handle of the image list.

If the function fails, the return value is NULL.

See Also

RGB


ImageList_Merge  (preliminaryWindows NT)
ImageList_Merge  (preliminary−Windows NT)

The ImageList_Merge function creates a new image by combining two existing images. The function also creates a new image list to store the image.

HIMAGELIST WINAPI ImageList_Merge(

HIMAGELIST  himl1,
int  i1,
HIMAGELIST  himl2,
int  i2,
int  dx,
int  dy
);
Parameters

himl1

Handle to the first image list.

i1

Index of the first existing image.

himl2

Handle to the second image list.

i2

Index of the second existing image.

dx and dy

Offset of the second image relative to the first image.

Return Value

If the function succeeds, the return value is the handle of the new image list.

If the function fails, the return value is NULL.

Remarks

The new image consists of the second existing image drawn transparently over the first. The mask for the new image is the result of performing a logical OR operation on the masks of the two existing images.


ImageList_Read  (preliminaryWindows NT)
ImageList_Read  (preliminary−Windows NT)

The ImageList_Read function reads an image list from a stream.

HIMAGELIST WINAPI ImageList_Read(

LPSTREAM  pstm
);
Parameters

pstm

Pointer to the stream.

Return Value

If the function succeeds, the return value is the image list.

If the function fails, the return value is NULL.


ImageList_Remove  (preliminaryWindows NT)
ImageList_Remove  (preliminary−Windows NT)

The ImageList_Remove function removes an image from an image list.

BOOL WINAPI ImageList_Remove(

HIMAGELIST  himl,
int  i
);
// Related macro

BOOL ImageList_RemoveAll(himl);

Parameters

himl

Handle to the image list.

i

Index of the image to remove. If the i parameter is  − 1, the function removes all images.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImageList_Replace  (preliminaryWindows NT)
ImageList_Replace  (preliminary−Windows NT)

The ImageList_Replace function replaces an image in an image list with a new image.

BOOL WINAPI ImageList_Replace(

HIMAGELIST  himl,
int  i,
HBITMAP  hbmImage,
HBITMAP  hbmMask
);
Parameters

himl

Handle to the image list.

i

Index of the image to replace.

hbmImage

Handle to the bitmap that contains the image.

hbmMask

Handle to the bitmap that contains the mask. If no mask is used with the image list, this parameter is ignored.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The ImageList_Replace function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and hbmMask after the function returns.

See Also

DeleteObject


ImageList_ReplaceIcon  (preliminaryWindows NT)
ImageList_ReplaceIcon  (preliminary−Windows NT)

The ImageList_ReplaceIcon function replaces an image with an icon or cursor.

int WINAPI ImageList_ReplaceIcon(

HIMAGELIST  himl,
int  i,
HICON  hicon
);
Parameters

himl

Handle to the image list.

i

Index of the image to replace.

hicon

Handle to the icon or cursor that contains the bitmap and mask for the new image.

Return Value

If the function succeeds, the return value is the index of the image.

If the function fails, the return value is  − 1.

Remarks

Because the system does not save hicon, you can destroy it after the function returns if the icon or cursor was created by the CreateIcon function. You do not need to destroy hicon if it was loaded by the LoadIcon function; the system automatically frees an icon resource when it is no longer needed.

See Also

CreateIcon, LoadIcon


ImageList_SetBkColor  (preliminaryWindows NT)
ImageList_SetBkColor  (preliminary−Windows NT)

The ImageList_SetBkColor function sets the background color for an image list.

COLORREF WINAPI ImageList_SetBkColor(

HIMAGELIST  himl,	//
COLORREF  clrBk	//
);
Parameters

himl

Handle to the image list.

clrBk

Background color to set. This parameter can be the CLR_NONE value; in that case, images are drawn transparently using the mask.

Return Value

If the function succeeds, the return value is the previous background color.

If the function fails, the return value is the CLR_NONE value.


ImageList_SetDragCursorImage  (preliminaryWindows NT)
ImageList_SetDragCursorImage  (preliminary−Windows NT)

The ImageList_SetDragCursorImage function creates a new drag image by combining the specified image (typically a mouse cursor image) with the current drag image.

BOOL WINAPI ImageList_SetDragCursorImage(

HIMAGELIST  himlDrag,
int  iDrag,
int  dxHotspot,
int  dyHotspot
);
Parameters

himlDrag

Handle to the image list that contains the new image to combine with the drag image.

iDrag

Index of the new image to combine with the drag image.

dxHotspot and dyHotspot

Position of the hot spot within the new image.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImageList_SetIconSize  (preliminaryWindows NT)
ImageList_SetIconSize  (preliminary−Windows NT)

The ImageList_SetIconSize function sets the dimensions of images in an image list and removes all images from the list.

BOOL WINAPI ImageList_SetIconSize(

HIMAGELIST  himl,
int  cx,
int  cy
);
Parameters

himl

Handle to the image list.

cx

Width, in pixels, of the images in the image list. All images in an image list have the same dimensions.

cy

Height, in pixels, of the images in the image list. All images in an image list have the same dimensions.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImageList_SetOverlayImage  (preliminaryWindows NT)
ImageList_SetOverlayImage  (preliminary−Windows NT)

The ImageList_SetOverlayImage function adds the index of an image to the list of images to be used as overlay masks. Up to four indices can be added to the list.

BOOL WINAPI ImageList_SetOverlayImage(

HIMAGELIST  himl,
int  iImage,
int  iOverlay
);
Parameters

himl

Handle to the image list.

iImage

Image to use as an overlay mask.

iOverlay

One-based index of the overlay mask.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

An overlay mask is an image drawn transparently over another image. You draw an overlay mask over an image by using the ImageList_Draw or ImageList_DrawEx function with the index of the overlay mask. The index must be specified by using the INDEXTOOVERLAYMASK macro.

See Also

ImageList_Draw, ImageList_DrawEx, INDEXTOOVERLAYMASK


ImageList_Write  (preliminaryWindows NT)
ImageList_Write  (preliminary−Windows NT)

The ImageList_Write function writes an image list to a stream.

HIMAGELIST WINAPI ImageList_Read(

HIMAGELIST  himl,	//
LPSTREAM  pstm	//
);
Parameters

himl

Handle to the image list.

pstm

Pointer to the stream.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImmAssociateContext  (preliminaryWindows 95)
ImmAssociateContext  (preliminary−Windows 95)

The ImmAssociateContext function associates the specified input context with the specified window. If hIMC is NULL, the function removes any association the window may have with an input context. By default, the system associates the default input context with each window as it is created.

HIMC ImmAssociateContext(

HWND  hWnd,
HIMC  hIMC
);
Parameters

hWnd

Handle to the window to be associated with the input context.

hIMC

Handle to the input context.

Return Value

Returns the handle to the input context previously associated with the window.

Remarks

If an application associates an input context with a window, the application must remove that association before destroying the input context. One way to do this is to save and reassociate the handle to the default input context with the window.


ImmConfigureIME  (preliminaryWindows 95)
ImmConfigureIME  (preliminary−Windows 95)

The ImmConfigureIME function displays the configuration dialog box for the IME.

BOOL ImmConfigureIME(

HKL  hKL,
HWND  hWnd,
DWORD  dwMode
);
Parameters

hKL

Handle to the keyboard layout.

hWnd

Handle to the parent window for the dialog box.

dwMode

Type of dialog box to display. This parameter can be one of the following values:

Value	Meaning
IME_CONFIG_GENERAL	Displays general purpose configuration dialog box.
IME_CONFIG_REGWORD	Displays register word dialog box.
IME_CONFIG_SELECTDICTIONARY	Displays dictionary selection dialog box.
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The ImmConfigureIME function is called by the Control Panel.


ImmCreateContext  (preliminaryWindows 95)
ImmCreateContext  (preliminary−Windows 95)

The ImmCreateContext function creates a new input context, allocating memory for the context and initializing it. An application calls this function to prepare its own input context.

HIMC ImmCreateContext(void);

Return Value

If the function succeeds, the return value is the handle to the new input context.

If the function fails, the return value is NULL.


ImmDestroyContext  (preliminaryWindows 95)
ImmDestroyContext  (preliminary−Windows 95)

The ImmDestroyContext function releases the input context and frees any memory associated with it.

BOOL ImmDestroyContext(

HIMC  hIMC
);
Parameters

hIMC

Handle to the input context to free.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Any application that creates an input context by using the ImmCreateContext function must call this function to free the context before it terminates.

See Also

ImmCreateContext


ImmEnumRegisterWord  (preliminaryWindows 95)
ImmEnumRegisterWord  (preliminary−Windows 95)

The ImmEnumRegisterWord function enumerates the register strings having the specified reading string, style, and register string.

UINT ImmEnumRegisterWord(

HKL  hKL,
REGISTERWORDENUMPROC  lpfnEnumProc,
LPCTSTR  lpszReading,
DWORD  dwStyle,
LPCTSTR  lpszRegister,
LPVOID  lpData
);
Parameters

hKL

Handle to the keyboard layout.

lpfnEnumProc

Pointer to the callback function. For more information, see EnumRegisterWordProc.

lpszReading

Pointer to the reading string to be enumerated. If NULL, this function enumerates all available reading strings that match with the specified dwStyle and lpszRegister.

dwStyle

Style to be enumerate. If zero, this function enumerates all available styles that match with the specified lpszReading and lpszRegister.

lpszRegister

Pointer to the register string to enumerate. If NULL, this function enumerates all register strings that match with the specified lpszReading and dwStyle.

lpData

Application-supplied data. The function passes this parameter to the callback function.

Return Value

Returns the last value return by the callback function. Its meaning is defined by the application. The function returns zero if it cannot enumerate the register strings.

Remarks

If dwStyle is zero and both lpszReading and lpszRegister are NULL, the ImmEnumRegisterWord function enumerates all register strings in the IME dictionary.

See Also

EnumRegisterWordProc


ImmEscape  (preliminaryWindows 95)
ImmEscape  (preliminary−Windows 95)

The ImmEscape function carries out IME-specific subfunctions and is used mainly for country-specific functions.

LRESULT ImmEscape(

HKL  hKL,
HIMC  hIMC,
UINT  uEscape,
LPVOID  lpData
);
Parameters

hKL

Handle to the keyboard layout.

hIMC

Handle to the input context.

uEscape

Index of the subfunction.

lpData

Subfunction-specific data.

Return Value

Returns zero on error; otherwise, returns an escape-specific value.


ImmGetCandidateList  (preliminaryWindows 95)
ImmGetCandidateList  (preliminary−Windows 95)

The ImmGetCandidateList function retrieves a specified candidate list, copying the list to the specified buffer.

DWORD ImmGetCandidateList(

HIMC  hIMC,
DWORD  deIndex,
LPCANDIDATELIST  lpCandList,
DWORD  dwBufLen
);
Parameters

hIMC

Handle to the input context.

deIndex

Zero-based index of the candidate list.

lpCandList

Pointer to the CANDIDATELIST structure that receives the candidate list.

dwBufLen

Size of the buffer, in bytes. If zero, the function returns the size in bytes required to receive the complete candidate list.

Return Value

If the function succeeds, the return value is the number of bytes copied to the specified buffer.

If the function fails, the return value is zero.

See Also

CANDIDATELIST


ImmGetCandidateListCount  (preliminaryWindows 95)
ImmGetCandidateListCount  (preliminary−Windows 95)

The ImmGetCandidateListCount function retrieves the size, in bytes, of the candidate lists.

DWORD ImeGetCandidateListCount(

HIMC  hIMC,
LPDWORD  lpdwListCount
);
Parameters

hIMC

Handle to the input context.

lpdwListCount

Pointer to the 32-bit variable that receives the size of the candidate lists.

Return Value

Returns the number of bytes required to receive all candidate lists.

Remarks

Applications typically call this function in response to a IMN_OPENCANDIDATE or IMN_CHANGECANDIDATE message.

See Also

IMN_CHANGECANDIDATE, IMN_OPENCANDIDATE


ImmGetCandidateWindow  (preliminaryWindows 95)
ImmGetCandidateWindow  (preliminary−Windows 95)

The ImmGetCandidateWindow function gets information about the candidate list window.

BOOL ImmGetCandidateWindow(

HIMC  hIMC,
DWORD  dwBufLen,
LPCANDIDATEFORM  lpCandidate
);
Parameters

hIMC

Handle to the input context.

dwBufLen

Size, in bytes, of the buffer that receives the information.

lpCandidate

Pointer to the CANDIDATEFORM structure that receives information about the candidate window.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

CANDIDATEFORM


ImmGetCompositionFont  (preliminaryWindows 95)
ImmGetCompositionFont  (preliminary−Windows 95)

The ImmGetCompositionFont function retrieves information about the logical font currently used to display characters in the composition window.

BOOL ImmGetCompositionFont(

HIMC  hIMC,
LPLOGFONT  lplf
);
Parameters

hIMC

Handle to the input context.

lplf

Pointer to a LOGFONT structure that receives the font information.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

LOGFONT


ImmGetCompositionString  (preliminaryWindows 95)
ImmGetCompositionString  (preliminary−Windows 95)

The ImmGetCompositionString function retrieves information about the composition string.

LONG ImmGetCompositionString(

HIMC  hIMC,
DWORD  dwIndex,
LPVOID  lpBuf,
DWORD  dwBufLen
);
Parameters

hIMC

Handle to the input context.

dwIndex

Index of the information to retrieve. For each value except GCS_CURSORPOS and GCS_DELTASTART, the function copies the requested information to the specified buffer. The function returns the cursor and delta position values in the low 16-bits of the return value.

lpBuf

Pointer to the buffer that receives the requested information.

dwBufLen

Size of the buffer, in bytes. If zero, the ImmGetCompositionString function returns the buffer size needed for the complete information.

Return Value

Returns the number of bytes copied to the destination buffer or, if dwBufLen is zero, the buffer size, in bytes, needed to receive all of the requested information. On an error, the function returns one of the following negative error values:

Value	Meaning
IMM_ERROR_NODATA	Composition data is not ready in the input context.
IMM_ERROR_GENERAL	General error detected by IME.
Remarks

An application calls this function in response to the WM_IME_COMPOSITION or WM_IME_STARTCOMPOSITION message. The IMM removes the information when an application calls the ImmReleaseContext function.

See Also

ImmReleaseContext, WM_IME_COMPOSITION


ImmGetCompositionWindow  (preliminaryWindows 95)
ImmGetCompositionWindow  (preliminary−Windows 95)

The ImmGetCompositionWindow function gets information about the composition window.

BOOL ImmGetCompositionWindow(

HIMC  hIMC,
LPCOMPOSITIONFORM  lpCompForm
);
Parameters

hIMC

Handle to the input context.

lpCompForm

Pointer to the COMPOSITIONFORM structure that receives information about the composition window.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

COMPOSITIONFORM


ImmGetContext  (preliminaryWindows 95)
ImmGetContext  (preliminary−Windows 95)

The ImmGetContext function retrieves the input context associated with the specified window.

HIMC ImmGetContext(

HWND  hWnd
);
Parameters

hWnd

Handle to the window to retrieve the input context for.

Return Value

Returns the handle to the input context.

Remarks

An application should routinely use this function to retrieve the current input context before attempting to access information in the context.


ImmGetConversionList  (preliminaryWindows 95)
ImmGetConversionList  (preliminary−Windows 95)

The ImmGetConversionList function retrieves the list of characters or words from one character or word.

UINT ImmGetConversionList(

HKL  hKL,
HIMC  hIMC,
LPCTSTR  lpSrc,
LPCANDIDATELIST  lpDst,
DWORD  dwBufLen,
UINT  uFlag
);
Parameters

hKL

Handle to the keyboard layout.

hIMC

Handle to the input context.

lpSrc

Pointer to a null-terminated character string.

lpDst

Pointer to the CANDIDATELIST structure that receives the conversion result.

dwBufLen

Size of the destination buffer, in bytes. If zero, the function returns the buffer size needed for the complete conversion result.

uFlag

Action flag. This parameter can be one of the following values:

Value	Meaning
GCL_CONVERSION	Source string is the reading string. The function copies the result string to the destination buffer.
GCL_REVERSECONVERSION	Source string is the result string. The function copies the reading string to the destination buffer.
GCL_REVERSE_LENGTH	Source string is the result string. The function returns the size in bytes of the reading string that would be created if GCL_REVERSECONVERSION were given.
Return Value

Returns the number of bytes copied to the specified buffer or, if dwBufLen is zero, the buffer size needed to receive the list.

See Also

CANDIDATELIST


ImmGetConversionStatus  (preliminaryWindows 95)
ImmGetConversionStatus  (preliminary−Windows 95)

The ImmGetConversionStatus function gets the current conversion status.

BOOL ImmGetConversionStatus(

HIMC  hIMC,
LPDWORD  lpfdwConversion,
LPDWORD  lpfdwSentence
);
Parameters

hIMC

Handle to the input context to retrieve information for.

lpfdwConversion

Pointer to a 32-bit variable that receives a combination of conversion mode values.

lpfdwSentence

Pointer to a 32-bit variable that receives a combination of sentence mode values.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Conversion and sentence mode values are set only if the IME supports those modes.


ImmGetDefaultIMEWnd  (preliminaryWindows 95)
ImmGetDefaultIMEWnd  (preliminary−Windows 95)

The ImmGetDefaultIMEWnd function gets the default window handle to the IME class.

HWND ImmGetDefaultIMEWnd(

HWND  hWnd
);
Parameters

hWnd

Handle to the window for the application.

Return Value

If the function succeeds, the return value is the default window handle to the IME class.

If the function fails, the return value is NULL.

Remarks

The system creates a default IME window for every thread. The IME window is created based on the IME class. The application can send WM_IME_CONTROL to this window.

See Also

WM_IME_CONTROL


ImmGetDescription  (preliminaryWindows 95)
ImmGetDescription  (preliminary−Windows 95)

The ImmGetDescription function copies the description of the IME to the specified buffer.

UINT ImmGetDescription(

HKL  hKL,
LPTSTR  lpszDescription,
UINT  uBufLen
);
Parameters

hKL

Handle to the keyboard layout.

lpszDescription

Pointer to the buffer that receives the null-terminated string describing the IME.

uBufLen

Size of the buffer, in bytes. If zero, the function returns the buffer size needed for the complete description, not including terminating null character.

Return Value

Returns the number of bytes copied to the buffer or, if uBufLen is zero, the buffer size in bytes needed to receive the description. Neither value includes the terminating null character.


ImmGetGuideLine  (preliminaryWindows 95)
ImmGetGuideLine  (preliminary−Windows 95)

The ImmGetGuideLine function gets information about errors. Applications use the information to notify users.

DWORD ImmGetGuideLine(dwBufLen

HIMC  hIMC,
DWORD  dwIndex,
LPTSTR  lpBuf,
DWORD  dwBufLen
);
Parameters

hIMC

Handle to the input context.

dwIndex

Type of guideline information to retrieve. Can be one of the following values:

Value	Meaning
GGL_LEVEL	Returns the error level.
GGL_INDEX	Returns the error index.
GGL_STRING	Retrieves the error message string.
GGL_PRIVATE	Returns information about reverse conversion.
lpBuf

Pointer to the buffer that receives the error message string. This parameter can be NULL if dwIndex is not GGL_STRING or GGL_PRIVATE if dwBufLen is zero.

dwBufLen

Size, in bytes, of the buffer pointed to by lpBuf. If zero, the function returns the buffer size needed to receive the error message string, not including the terminating null character.

Return Value

The return value is an error level, an error index, or the size of an error message string, depending on the value of the dwIndex parameter. If dwIndex is GGL_LEVEL, the return value is one of the following:

Value	Meaning
GL_LEVEL_ERROR	Error. The IME may not be able to continue.
GL_LEVEL_FATAL	Fatal error. The IME cannot continue, and data may be lost.
GL_LEVEL_INFORMATION	No error, but information is available for the user.
GL_LEVEL_NOGUIDELINE	No error. Remove previous error message if still visible.
GL_LEVEL_WARNING	Unexpected input or other result. The user should be warned, but the IME can continue.
If dwIndex is GGL_INDEX, the return value is one of the following:

Value	Meaning
GL_ID_CANNOTSAVE	The dictionary or the statistics data cannot be saved.
GL_ID_NOCONVERT	The IME cannot convert any more.
GL_ID_NODICTIONARY	The IME cannot find the dictionary, or the dictionary has an unexpected format.
GL_ID_NOMODULE	The IME can not find the module that IME needs.
GL_ID_READINGCONFLICT	For example, some vowels cannot put together.
GL_ID_TOOMANYSTROKE	There are too many strokes for one character or one clause.
GL_ID_TYPINGERROR	Typing error. The IME can not handle this typing.
GL_ID_UNKNOWN	Unknown error. The application should refer to the error message string.
GL_ID_INPUTREADING	IME accepts reading character input.
GL_ID_INPUTRADICAL	IME accepts radical character input.
GL_ID_INPUTCODE	IME accepts character code input.
GL_ID_CHOOSECANDIDATE	IME accepts candidate string selection.
GL_ID_REVERSECONVERSION	Information about reverse conversion is available.
If dwIndex is GGL_STRING, the return value is the number of bytes of the string copied to the buffer, or if dwBufLen is zero, the return value is the buffer size needed to receive the string.

If dwIndex is GGL_PRIVATE, the return value is the number of bytes of information copied to the buffer. If dwIndex is GGL_PRIVATE and dwBufLen is zero, the return value is the buffer size needed to receive the information.

Remarks

Applications typically call this function after receiving an IMN_GUIDELINE message.


ImmGetIMEFileName  (preliminaryWindows 95)
ImmGetIMEFileName  (preliminary−Windows 95)

The ImmGetIMEFileName function gets the filename of the IME associated with the specified keyboard layout.

BOOL ImmGetIMEFileName(

HKL  hKL,
LPTSTR  lpszFileName,
UINT  uBufLen
);
Parameters

hKL

Handle to the keyboard layout.

lpszFileName

Pointer to the buffer that receives the filename.

uBufLen

Size in bytes of the buffer. If zero, the function returns the buffer size in bytes needed to receive the filename, not including the termintaing null character.

Return Value

The return value is the number of bytes in the filename copied to the buffer, or if uBufLen is zero, the return value is the buffer size needed for the filename. In either case, the terminating null character is not included.

Remarks

In the registry, the system stores the filename as the IME name value in HKEY_LOCAL_MACHINE root under the \System\CurrentControlSet\control\keyboard layouts\hKL key.


ImmGetOpenStatus  (preliminaryWindows 95)
ImmGetOpenStatus  (preliminary−Windows 95)

The ImmGetOpenStatus function checks whether the IME is open or closed.

BOOL WINAPI ImmGetOpenStatus(

HIMC  hIMC
);
Parameters

hIMC

Handle to the input context.

Return Value

The return value is TRUE if the IME is open, FALSE otherwise.


ImmGetProperty  (preliminaryWindows 95)
ImmGetProperty  (preliminary−Windows 95)

The ImmGetProperty function gets the property and capabilities of the IME associated with the specified keyboard layout.

BOOL ImmGetProperty(

HKL  hKL,
DWORD  fdwIndex
);
Parameters

hKL

Handle to the keyboard layout.

fdwIndex

Type of property information to retrieve. This parameter can be one of the following values:

Value	Meaning
IGP_PROPERTY	Property information.
IGP_CONVERSION	Conversion capabilities.
IGP_SENTENCE	Sentence mode capabilities.
IGP_UI	User interface capabilities.
IGP_SETCOMPSTR	Composition string capabilities.
IGP_SELECT	Selection inheritance capabilities.
Return Value

Returns the property or capability value, depending on the value of the dwIndex parameter. If dwIndex is IGP_PROPERTY, returns a combination of the following values:

Value	Meaning
IME_PROP_AT_CARET	If set, conversion window is at the caret position. If clear, the window is near caret position.
IME_PROP_SPECIAL_UI	If set, IME has a nonstandard user interface. The application should not draw in the IME window.
IME_PROP_CANDLIST_START_FROM_1	If set, strings in the candidate list are numbered starting at 1. If clear, strings start at 0.
IME_PROP_UNICODE	If set, strings for the input context have Unicode characters. If clear, strings have single and double-byte characters.
If dwIndex is IGP_UI, the return value is a combination of the following values:

Value	Meaning
UI_CAP_2700	Supports text escapement values of 0 or 2700.
UI_CAP_ROT90	Supports text escapement values of 0, 900, 1800, or 2700.
UI_CAP_ROTANY	Supports any text escapement value.
If dwIndex is IGP_SETCOMPSTR, the return value is a combination of the following values:

Value	Meaning
SCS_CAP_COMPSTR	Can create the composition string by using the SCS_SETSTR value of the ImmSetCompositionString function.
SCS_CAP_MAKEREAD	Can create the reading string from corresponding composition string when using the SCS_SETSTR value of the ImmSetCompositionString function.
If dwIndex is IGP_SELECT, the return value is a combination of the following values:

Value	Meaning
SELECT_CAP_CONVMODE	Inherits conversion mode when a new IME is selected.
SELECT_CAP_SENTENCE	Inherits sentence mode when a new IME is selected.


ImmGetRegisterWordStyle  (preliminaryWindows 95)
ImmGetRegisterWordStyle  (preliminary−Windows 95)

The ImmGetRegisterWordStyle function gets a list of the styles support by the IME associated with the specified keyboard layout.

UINT ImmGetRegisterWordStyle(

HKL  hKL,
UINT  nItem,
LPSTYLEBUF  lpStyleBuf
);
Parameters

hKL

Handle to the keyboard layout.

nItem

Maximum number of styles that the buffer can hold.

lpStyleBuf

Pointer to the STYLEBUF structure that receives the style information.

Return Value

The return value is the number of layout handles copied to the buffer, or if nItems is zero, the return value is the buffer size in array elements needed to receive all available style information.

See Also

STYLEBUF


ImmGetStatusWindowPos  (preliminaryWindows 95)
ImmGetStatusWindowPos  (preliminary−Windows 95)

The ImmGetStatusWindowPos function gets the position of the status window.

BOOL ImmGetStatusWindowPos(

HIMC  hIMC,
LPPOINT  lpptPos
);
Parameters

hIMC

Handle to the input context.

lpptPos

Pointer to the POINT structure that receives the position coordinates. These are screen coordinates, relative to the upper-left corner of the screen.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

POINT


ImmGetVirtualKey  (preliminaryWindows 95)
ImmGetVirtualKey  (preliminary−Windows 95)

The ImmGetVirtualKey function recovers the original virtual-key value associated with a key input message that has already been processed by the IME.

UINT ImmGetVirtualKey(

HWND  hWnd
);
Parameters

hWnd

Handle to the window that receives the key message.

Return Value

The return value is the original virtual-key value.

Remarks

Although the IME sets the virtual-key value to VK_PROCESSKEY after processing a key input message, an application can recover the original virtual-key value with the ImmGetVirtualKey function. This function can be used only for key input messages containing the VK_PROCESSKEY value.


ImmInstallIME  (preliminaryWindows 95)
ImmInstallIME  (preliminary−Windows 95)

The ImmInstallIME function installs an IME into the system.

HKL ImmInstallIME(

LPCTSTR  lpszIMEFileName,
LPCTSTR  lpszLayoutText
);
Parameters

lpszIMEFileName

Pointer to a null-terminated string that specifies the full path of the IME.

lpszLayoutText

Pointer to a null-terminated string that specifies the name of the IME. This name also specifies the layout text of the IME.

Return Value

The return value is the handle to the keyboard layout for the IME.

Remarks

This function is intended to be used by IME setup programs only.


ImmIsIME  (preliminaryWindows 95)
ImmIsIME  (preliminary−Windows 95)

The ImmIsIME function checks whether the specified handle identifies an IME.

BOOL ImmIsIME(

HKL  hKL
);
Parameters

hKL

Handle to the keyboard layout to check.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImmIsUIMessage  (preliminaryWindows 95)
ImmIsUIMessage  (preliminary−Windows 95)

The ImmIsUIMessage function checks for messages intended for the IME window and sends those messages to the specified window.

BOOL ImmIsUIMessage(

HWND  hWndIME,
UINT  msg,
WPARAM  wParam,
LPARAM  lParam
);
Parameters

hWndIME

Handle to a window belonging to the IME window class.

msg

Message to check.

wParam

32-bit message-specific parameter.

lParam

32-bit message-specific parameter.

Return Value

If the message is processed by the IME window, the return value is TRUE.

If the message is not processed by the IME window, the return value is FALSE.

Remarks

An application typically uses this function to display any composition string or candidate list specified by IME. If hWndIME is NULL, the function checks whether the message is a user interface message.


ImmNotifyIME  (preliminaryWindows 95)
ImmNotifyIME  (preliminary−Windows 95)

The ImmNotifyIME function notifies the IME about changes to the status of the input context.

BOOL ImmNotifyIME(

HIMC  hIMC,
DWORD  dwAction,
DWORD  dwIndex,
DWORD  dwValue
);
Parameters

hIMC

Handle to the input context.

dwAction

Notification code. This parameter can be one of the following values:

Value	Meaning
NI_CHANGECANDIDATELIST	An application changed the current selected candidate; dwIndex is an index of a candidate list to be selected and dwValue is not used.
NI_CLOSECANDIDATE	An application directs the IME to close a candidate list; dwIndex is the index of the list to close; dwValue is not used. The IME sends a IMN_CLOSECANDIDATE message to the application if it closes the list.
NI_COMPOSITIONSTR	An application directs the IME to carry out an action on the composition string; dwValue is not used and dwIndex can be CPS_CANCEL, CPS_COMPLETE, CPS_CONVERT, or CPS_REVERT.
NI_OPENCANDIDATE	An application directs the IME to open a candidate list; dwIndex is the index of the list to open; dwValue is not used. The IME sends a IMN_OPENCANDIDATE message to the application if it opens the list.
NI_SELECTCANDIDATESTR	An application selected one of candidates; dwIndex is an index of a candidate list to be selected and dwValue is an index of a candidate string in the selected candidate list.
NI_SETCANDIDATE_PAGESIZE	The dwIndex parameter specifies the candidate list to be changed and must have a value in the range 0 to 31.
NI_SETCANDIDATE_PAGESTART	The dwIndex parameter specifies the candidate list to be changed and must have a value in the range 0 to 31.
dwIndex

Index of a candidate list or, if dwAction is NI_COMPOSITIONSTR, one of the following values:

Value	Meaning
CPS_CANCEL	Clear the composition string and set the status to no composition string.
CPS_COMPLETE	Set the composition string as the result string.
CPS_CONVERT	Convert the composition string.
CPS_REVERT	Cancel the current composition string and revert to the unconverted string.
dwValue

Index of a candidate string or not used, depending on the value of the dwAction parameter.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImmRegisterWord  (preliminaryWindows 95)
ImmRegisterWord  (preliminary−Windows 95)

The ImmRegisterWord function registers a string into the dictionary of the IME associated with the specified keyboard layout.

BOOL ImmRegisterWord(

HKL  hKL,
LPCTSR  lpszReading,
DWORD  dwStyle,
LPCTSTR  lpszRegister
);
Parameters

hKL

Handle to the keyboard layout.

lpszReading

Pointer to a null-terminated string specifying the reading string associated with the string to register.

dwStyle

Style of the register string. This parameter can be IME_REGWORD_STYLE_EUDC to indicate the string is in the EUDC range, or any value in the reserved range IME_REGWORD_STYLE_USER_FIRST to IME_REGWORD_STYLE_USER_LAST to indicate a private style maintained by the specified IME.

lpszRegister

Pointer to a null-terminated string specifying the string to register.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImmReleaseContext  (preliminaryWindows 95)
ImmReleaseContext  (preliminary−Windows 95)

The ImmReleaseContext function releases the input context and unlocks the memory associated in the context. An application must call this function for each call to the ImmGetContext function.

BOOL ImmReleaseContext(

HWND  hWnd,
HIMC  hIMC
);
Parameters

hWnd

Handle to the window for which the input context was previously retrieved.

hIMC

Handle to the input context.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

ImmGetContext


ImmSetCandidateWindow  (preliminaryWindows 95)
ImmSetCandidateWindow  (preliminary−Windows 95)

The ImmSetCandidateWindow function sets information about the candidate list window.

BOOL ImmSetCandidateWindow(

HIMC  hIMC,
LPCANDIDATEFORM  lpCandidate
);
Parameters

hIMC

Handle to the input context.

lpCandidate

Pointer to the CANDIDATEFORM structure that contains information about the candidate window.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

ImmSetCandidateWindow causes an IMN_SETCANDIDATEPOS message to be sent to the application.

See Also

CANDIDATEFORM


ImmSetCompositionFont  (preliminaryWindows 95)
ImmSetCompositionFont  (preliminary−Windows 95)

The ImmSetCompositionFont function sets the logical font to be used to display characters in the composition window.

BOOL ImmSetCompositionFont(

HIMC  hIMC,
LPLOGFONT  lplf
);
Parameters

hIMC

Handle to the input context.

lplf

Pointer to the LOGFONT structure containing the font information to set.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Even if an application never uses the composition window, it must set the appropriate font to ensure that characters are displayed properly. This is especially true for vertical writing.

This function causes a IMN_SETCOMPOSITIONFONT message to be sent to the application.

See Also

IMN_SETCOMPOSITIONFONT, LOGFONT


ImmSetCompositionString  (preliminaryWindows 95)
ImmSetCompositionString  (preliminary−Windows 95)

The ImmSetCompositionString function sets the characters, attributes, and clauses of the composition and reading strings.

BOOL ImmSetCompositionString(

HIMC  hIMC,
DWORD  dwIndex,
LPCVOID  lpComp,
DWORD  dwCompLen,
LPCVOID  lpRead,
DWORD  dwReadLen
);
Parameters

hIMC

Handle to the input context.

dwIndex

Type of information to set. This parameter can be one of one of the following values:

Value	Meaning
SCS_SETSTR	Sets the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid string. If either string is too long, the IME truncates it.
SCS_CHANGEATTR	Sets attributes for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid attribute array.
SCS_CHANGECLAUSE	Sets the clause information for the composition string, the reading string, or both. At least one of the lpComp and lpRead parameters must point to a valid clause information array.
lpComp

Pointer to the buffer containing the information to set for the composition string. The information is as specified by the dwIndex value.

dwCompLen

Size in bytes of the information buffer for the composition string.

lpRead

Pointer to the buffer containing the information to set for the reading string. The information is as specified by the dwIndex value.

dwReadLen

Size, in bytes, of the information buffer for the reading string.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

When changing attributes, all characters in a clause must have the same attribute. Converted characters must be either ATTR_CONVERTED or ATTR_TARGET_CONVERTED; unconverted characters either ATTR_INPUT or ATTR_TARGET_NOTCONVERTED.

When changing clause information, only the target clause can be changed and only one boundary of the clause can be changed at a time. The target clause has the ATTR_TARGET_CONVERTED or ATTR_TARGET_NOTCONVERTED attribute.

When the IME completes the changes, it sends a WM_IME_COMPOSITION message to the application notifying it of the changes.

See Also

WM_IME_COMPOSITION


ImmSetCompositionWindow  (preliminaryWindows 95)
ImmSetCompositionWindow  (preliminary−Windows 95)

The ImmSetCompositionWindow function sets the position of the composition window.

BOOL ImmSetCompositionWindow(

HIMC  hIMC,
LPCOMPOSITIONFORM  lpCompForm
);
Parameters

hIMC

Handle to the input context.

lpCompForm

Pointer to the COMPOSITIONFORM structure that contains the new position and other related information about the composition window.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The ImmSetCompositionWindow function causes a IMN_SETSCOMPOSITIONWINDOW message to be sent to the application.

See Also

COMPOSITIONFORM


ImmSetConversionStatus  (preliminaryWindows 95)
ImmSetConversionStatus  (preliminary−Windows 95)

The ImmSetConversionStatus function sets the current conversion status.

BOOL ImmSetConversionStatus(

HIMC  hIMC,
DWORD  fdwConversion,
DWORD  fdwSentence
);
Parameters

hIMC

Handle to the input context.

fdwConvStatus

Conversion mode values.

fdwSentence

Sentence mode values.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

This function sends a IMN_SETCONVERSIONSTATUS message to the application.


ImmSetOpenStatus  (preliminaryWindows 95)
ImmSetOpenStatus  (preliminary−Windows 95)

The ImmSetOpenStatus function opens or closes the IME.

BOOL ImmSetOpenStatus(

HIMC  hIMC,
BOOL  fOpen
);
Parameters

hIMC

Handle to the input context.

fOpen

Open flag. If TRUE, the IME is opened; otherwise, it is closed.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

This function causes a IMN_SETOPENSTATUS message to be sent to the application.

See Also

IMN_SETOPENSTATUS


ImmSetStatusWindowPos  (preliminaryWindows 95)
ImmSetStatusWindowPos  (preliminary−Windows 95)

The ImmSetStatusWindowPos function sets the position of the status window.

BOOL ImmSetStatusWindowPos(

HIMC  hIMC,
LPPOINT  lpptPos
);
Parameters

hIMC

Handle to the input context.

lpptPos

Pointer to the POINT structure that receives the new position of the status window.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The ImmSetStatusWindowPos function causes a IMN_SETSTATUSWINDOWPOS message to be sent to the application.

See Also

IMN_SETSTATUSWINDOWPOS, POINT


ImmSimulateHotKey  (preliminaryWindows 95)
ImmSimulateHotKey  (preliminary−Windows 95)

The ImmSimulateHotKey function simulates the specified IME hot key, causing the same response as if the user had pressed the hot key in the specified window.

BOOL ImmSimulateHotKey(

HWND  hWnd,
DWORD  dwHotKeyID
);
Parameters

hWnd

Handle to the window.

dwHotKeyID

Identifier of the IME hot key.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImmUnregisterWord  (preliminaryWindows 95)
ImmUnregisterWord  (preliminary−Windows 95)

The ImmUnregisterWord function removes a register string from the dictionary of the IME associated with the specified keyboard layout.

BOOL ImmUnregisterWord(

HKL  hKL,
LPCTSTR  lpszReading,
DWORD  dwStyle,
LPCTSTR  lpszUnregister
);
Parameters

hKL

Handle to the keyboard layout.

lpszReading

Pointer to a null-terminated string specifying the reading string associated with the string to remove.

dwStyle

Style of the register string. Can be IME_REGWORD_STYLE_EUDC to indicate the string is in the EUDC range, or any value in the reserved range IME_REGWORD_STYLE_USER_FIRST to IME_REGWORD_STYLE_USER_LAST to indicate a private style maintained by the specified IME.

lpszUnregister

Pointer to a null-terminated string specifying the register string to remove.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


ImpersonateDdeClientWindow

The ImpersonateDdeClientWindow function enables a DDE server application to impersonate a DDE client application's security context in order to protect secure server data from unauthorized DDE clients.

BOOL ImpersonateDdeClientWindow(

HWND  hWndClient,	// handle of DDE client window
HWND  hWndServer	// handle of DDE server window
);
Parameters

hWndClient

Identifies the DDE client window to impersonate. The client window must have established a DDE conversation with the server window identified by the hWndServer parameter.

hWndServer

Identifies the DDE server window. An application must create the server window before calling this function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application should call the RevertToSelf function to undo the impersonation set by the ImpersonateDdeClientWindow function.

A DDEML application should use the DdeImpersonateClient function.

See Also

DdeImpersonateClient, RevertToSelf


ImpersonateLoggedOnUser  (preliminaryWindows NT)
ImpersonateLoggedOnUser  (preliminary−Windows NT)

The ImpersonateLoggedOnUser function lets the calling thread impersonate a user. The user is represented by a token handle obtained by calling the LogonUser function.

BOOL ImpersonateLoggedOnUser(

HANDLE hToken	// handle to a token that represents a logged-on user
);
Parameters

hToken

Handle to a token that represents a logged-on user. You obtain this token handle by calling the LogonUser function.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateProcessAsUser, LogonUser


ImpersonateNamedPipeClient

The ImpersonateNamedPipeClient function impersonates a named-pipe client application.

BOOL ImpersonateNamedPipeClient(

HANDLE  hNamedPipe	// handle of a named pipe
);
Parameters

hNamedPipe

Identifies a named pipe.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The ImpersonateNamedPipeClient function allows the server end of a named pipe to impersonate the client end. When this function is called, the named-pipe file system changes the thread of the calling process to start impersonating the security context of the last message read from the pipe. Only the server end of the pipe can call this function.

The server can call the RevertToSelf function when the impersonation is complete.

See Also

DdeImpersonateClient, DuplicateToken, RevertToSelf


ImpersonateSelf

The ImpersonateSelf function obtains an access token that impersonates the security context of the calling process. The token is assigned to the calling thread.

BOOL ImpersonateSelf(

SECURITY_IMPERSONATION_LEVEL  ImpersonationLevel	// impersonation level
);
Parameters

ImpersonationLevel

Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that supplies the impersonation level of the new token.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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


inet_addr

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

unsigned long inet_addr (

const char FAR * cp
);
Parameters

cp

A character string representing a number expressed in the Internet standard "." notation.

Return Value

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

Remarks

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

Internet Addresses

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

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

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

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

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

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

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

See Also

inet_ntoa


inet_ntoa

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

char FAR * inet_ntoa (

struct in_addr in
);
Parameters

in

A structure that represents an Internet host address.

Return Value

If the function succeeds, inet_ntoa returns a char pointer to a static buffer containing the text address in standard "." notation.

If the function fails, it returns NULL. The data should be copied before another Windows Sockets call is made.

Remarks

This function takes an Internet address structure specified by the in parameter. It returns an ASCII string representing the address in "." notation as "a.b.c.d". Note that the string returned by inet_ntoa resides in memory allocated by the Windows Sockets implementation. If the application needs to use the memory differently, it should copy the information to a private application buffer. The data is guaranteed to be valid until the next Windows Sockets function call within the same thread, but no longer.

See Also

inet_addr


InflateRect

The InflateRect function increases or decreases the width and height of the specified rectangle. The InflateRect function adds dx units to the left and right ends of the rectangle and dy units to the top and bottom. The dx and dy parameters are signed values; positive values increase the width and height, and negative values decrease them.

BOOL InflateRect(

LPRECT  lprc,	// address of rectangle
int  dx,	// amount to increase or decrease width
int  dy	// amount to increase or decrease height
);
Parameters

lprc

Points to the RECT structure that increases or decreases in size.

dx

Specifies the amount to increase or decrease the rectangle width. This parameter must be negative to decrease the width.

dy

Specifies the amount to increase or decrease the rectangle height. This parameter must be negative to decrease the height.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

IntersectRect, OffsetRect, RECT, UnionRect


InitAtomTable

The InitAtomTable function initializes the local atom table and sets it to the specified size.

BOOL InitAtomTable(

DWORD  nSize	// size of atom table
);
Parameters

nSize

Specifies the size, in table entries, of the atom table. This value should be a prime number.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

An application need not use this function to use a local atom table. The default size of the local and global atom tables is 37 table entries. If an application does use InitAtomTable, however, it should call the function before any other atom-management function.

If an application uses a large number of local atoms, it can reduce the time required to add an atom to the local atom table or to find an atom in the table by increasing the size of the table. However, this increases the amount of memory required to maintain the table.

The size of the global atom table cannot be changed.

See Also

AddAtom, DeleteAtom, FindAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName


InitCommonControls  (preliminaryWindows NT)
InitCommonControls  (preliminary−Windows NT)

The InitCommonControls function ensures that the common control dynamic-link library (DLL) is loaded.

void InitCommonControls(VOID);

Return Value

This function does not return a value.


InitializeAcl

The InitializeAcl function creates a new ACL structure.

An ACL is an access-control list.

BOOL InitializeAcl(

PACL  pAcl,	// address of access-control list
DWORD  nAclLength,	// size of access-control list
DWORD  dwAclRevision	// revision level of access-control list
);
Parameters

pAcl

Points to an ACL structure initialized by this function.

nAclLength

Specifies the length, in bytes, of the buffer pointed to by the pAcl parameter. This value must be large enough to contain the ACL header and all of the access-control entries (ACEs) to be stored in the ACL.

When calculating the size of an ACL, note that each ACE in an ACL gets the SID specified by its SidStart member copied to the ACE structure, starting at the ACE's SidStart member. Thus, each ACE added to the ACL requires room for the ACE plus room for its SID minus the size of the SidStart member (a DWORD).

For example, the size of an ACL buffer large enough to contain a single ACCESS_ALLOWED_ACE is :

    cbAcl =    sizeof(ACL) + sizeof(ACCESS_ALLOWED_ACE)

             + GetLengthSid(pSid) - sizeof(DWORD) ;

Another example: the size of an ACL buffer large enough to contain seven ACCESS_DENIED_ACE structures is :

    cbAcl =  sizeof(ACL) +  7 * ( sizeof(ACCESS_DENIED_ACE) - sizeof(DWORD)) +

             GetLengthSid(pSid1) + GetLengthSid(pSid2) + ... + GetLengthSid(pSid7)

dwAclRevision

Specifies the revision level of the ACL. This parameter must be set to the current revision level, defined as ACL_REVISION for this version of Windows.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The ACL initialized by this function contains no ACEs. It is empty, as opposed to being a nonexistent ACL. If an empty ACL is applied to an object, it implicitly denies all access to that object.

See Also

ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACL, AddAccessAllowedAce, AddAccessDeniedAce, AddAce, AddAuditAccessAce, DeleteAce, GetAce, GetAclInformation, IsValidAcl, SetAclInformation, SID,


InitializeCriticalSection

The InitializeCriticalSection function initializes a critical section object.

VOID InitializeCriticalSection(

LPCRITICAL_SECTION  lpCriticalSection	// address of critical section object
);
Parameters

lpCriticalSection

Points to the critical section object.

Return Value

This function does not return a value.

Remarks

The threads of a single process can use a critical section object for mutual-exclusion synchronization. The process is responsible for allocating the memory used by a critical section object, which it can do by declaring a variable of type CRITICAL_SECTION. Before using a critical section, some thread of the process must call the InitializeCriticalSection function to initialize the object.

Once a critical section object has been initialized, the threads of the process can specify the object in the EnterCriticalSection 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 (API) to manage critical section objects.

See Also

CreateMutex, DeleteCriticalSection, EnterCriticalSection, LeaveCriticalSection


InitializeSecurityDescriptor

The InitializeSecurityDescriptor function initializes a new security descriptor.

BOOL InitializeSecurityDescriptor(

PSECURITY_DESCRIPTOR  pSecurityDescriptor,	// address of security descriptor
DWORD  dwRevision	// revision level
);
Parameters

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure that the function initializes.

dwRevision

Specifies the revision level to assign to the security descriptor. This must be SECURITY_DESCRIPTOR_REVISION.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The InitializeSecurityDescriptor function initializes a security descriptor in absolute format, rather than self-relative format.

The InitializeSecurityDescriptor function initializes a security descriptor to have no system ACL, no discretionary ACL, no owner, no primary group, and all control flags set to FALSE (NULL). Thus, except for its revision level, it is empty.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl


InitializeSid

The InitializeSid function initializes a SID structure. An SID is a security identifier.

BOOL InitializeSid(

PSID  Sid,	// address of SID to initialize
PSID_IDENTIFIER_AUTHORITY  pIdentifierAuthority,	// address of identifier authority
BYTE  nSubAuthorityCount	// count of subauthorities
);
Parameters

Sid

Points to a SID structure to be initialized.

pIdentifierAuthority

Points to a SID_IDENTIFIER_AUTHORITY structure to set in the SID structure.

nSubAuthorityCount

Specifies the number of subauthorities to set in the SID. Values of the subauthority must be set separately, as described in the following Remarks section.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Although the InitializeSid function sets the number of subauthorities for the SID, it does not set the subauthority values. This must be done separately, using functions, such as GetSidSubAuthority.

An application can use the AllocateAndInitializeSid function to initialize a SID and set its subauthority values.

See Also

AllocateAndInitializeSid, GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, IsValidSid, SID, SID_IDENTIFIER_AUTHORITY


InitiateSystemShutdown

The InitiateSystemShutdown function initiates a shutdown and optional restart of the specified computer.

BOOL InitiateSystemShutdown(

LPTSTR  lpMachineName,	// address of name of computer to shut down
LPTSTR  lpMessage,	// address of message to display in dialog box
DWORD  dwTimeout,	// time to display dialog box
BOOL  bForceAppsClosed,	// force applications with unsaved changes flag
BOOL  bRebootAfterShutdown	// reboot flag
);
Parameters

lpMachineName

Points to the null-terminated string that specifies the network name of the computer to shut down. If lpMachineName is NULL or points to an empty string, the function shuts down the local computer.

lpMessage

Points to a null-terminated string that specifies a message to display in the shutdown dialog box. This parameter can be NULL if no message is required.

dwTimeout

Specifies the time (in seconds) that the dialog box should be displayed. While this dialog box is displayed, the shutdown can be stopped by the AbortSystemShutdown function.

If dwTimeout is not zero, InitiateSystemShutdown displays a dialog box on the specified computer. The dialog box displays the name of the user who called the function, displays the message specified by the lpMessage parameter, and prompts the user to log off. The dialog box beeps when it is created and remains on top of other windows in the system. The dialog box can be moved but not closed. A timer counts down the remaining time before a forced shutdown. If the user logs off, the system shuts down immediately. Otherwise, the computer is shut down when the timer expires.

If dwTimeout is zero, the computer shuts down without displaying the dialog box, and the shutdown cannot be stopped by AbortSystemShutdown.

bForceAppsClosed

Specifies whether applications with unsaved changes are to be forcibly closed. If this parameter is TRUE, such applications are closed. If this parameter is FALSE, a dialog box is displayed prompting the user to close the applications.

bRebootAfterShutdown

Specifies whether the computer is to restart immediately after shutting down. If this parameter is TRUE, the computer is to restart. If this parameter is FALSE, the system flushes all caches to disk, clears the screen, and displays a message indicating that it is safe to power down.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

To shut down the local computer, the calling process must have the SE_SHUTDOWN_NAME privilege. To shut down a remote computer, the calling process must have the SE_REMOTE_SHUTDOWN_NAME privilege on the remote computer. By default, users can enable the SE_SHUTDOWN_NAME privilege on the computer they are logged onto, and administrators can enable the SE_REMOTE_SHUTDOWN_NAME privilege on remote computers.

Common failures include an invalid or inaccessible computer name or insufficient privilege.

See Also

AbortSystemShutdown


InSendMessage

The InSendMessage function specifies whether the current window procedure is processing a message that was sent from another thread by a call to the SendMessage function.

BOOL InSendMessage(VOID)

Parameters

This function has no parameters.

Return Value

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

The InsertMenu function inserts a new menu item into a menu, moving other items down the menu.

BOOL InsertMenu(

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
);
Parameters

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 following Remarks section.

Value	Description
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 has the MF_POPUP flag set, 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	Description
MF_BITMAP	Contains a bitmap handle.
MF_OWNERDRAW	Contains a 32-bit value supplied by the application that can be used to maintain additional data related to the menu item. The value is in the itemData member of the structure pointed to by the lparam parameter of the WM_MEASUREITEM or WM_DRAWITEM message sent when the menu item is created or its appearance is updated.
MF_STRING	Contains a pointer to a null-terminated string (the default).
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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	Description
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 SetMenuItemBitmaps), this flag displays the check mark bitmap next to the menu item.
MF_DISABLED	Disables the menu item so that it cannot be selected, but does not gray it.
MF_ENABLED	Enables the menu item so that it can be selected and restores it from its grayed state.
MF_GRAYED	Disables the menu item and grays it so it cannot be selected.
MF_MENUBARBREAK	Functions the same as the MF_MENUBREAK flag 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 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, WM_DRAWITEM, WM_MEASUREITEM


InsertMenuItem  (preliminaryWindows 95)
InsertMenuItem  (preliminary−Windows 95)

The InsertMenuItem function inserts a new menu item at the specified position in a menu bar or pop-up menu.

BOOL WINAPI InsertMenuItem(

HMENU  hMenu,
UINT  uItem,
BOOL  fByPosition,
LPMENUITEMINFO  lpmii
);
Parameters

hMenu

Handle to the menu in which the new menu item is inserted.

uItem

Identifier or position of the menu item before which to insert the new item. The meaning of this parameter depends on the value of fByPosition.

fByPosition

Value specifying the meaning of uItem. If this parameter is FALSE, uItem is a menu item identifier. Otherwise, it is a menu item position.

lpmii

Pointer to a MENUITEMINFO structure that contains information about the new menu item.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

See Also

MENUITEMINFO


Int32x32To64

The Int32x32To64 function multiplies two signed 32-bit integers, returning a signed 64-bit integer result. The function performs optimally on all Win32 platforms.

LONGLONG Int32x32To64(

LONG  Multiplier,	// specifies first signed 32-bit integer for the multiplication
LONG  Multiplicand	// specifies second signed 32-bit integer for the multiplication
);
Parameters

Multiplier

Specifies the first signed 32-bit integer for the multiplication.

Multiplicand

Specifies the second signed 32-bit integer for the multiplication.

Return Value

The return value is the signed 64-bit integer result of the multiplication.

Remarks

This function is implemented on all platforms by optimal inline code: a single multiply instruction that returns a 64-bit result.

Please note that the function's return value is a 64-bit value, not a LARGE_INTEGER structure.

See Also

UInt32x32To64


Int64ShllMod32

The Int64ShllMod32 function performs a left logical shift operation on an unsigned 64-bit integer value. The function provides improved shifting code for left logical shifts where the shift count is in the range 0 − 31.

DWORDLONG Int64ShllMod32(

DWORDLONG  Value,	// specifies unsigned 64-bit integer to shift left logically
DWORD  ShiftCount	// specifies a shift count in the range 0 − 31
);
Parameters

Value

Specifies the unsigned 64-bit integer to be shifted.

ShiftCount

Specifies a shift count in the range 0 − 31.

Return Value

The return value is the unsigned 64-bit integer result of the left logical shift operation.

Remarks

The shift count is the number of bit positions that the value's bits move.

In a left logical shift operation on an unsigned value, the value's bits move to the left, and vacated bits on the right side of the value are set to zero.

A compiler can generate optimal code for a left logical shift operation when the shift count is a constant. However, if the shift count is a variable whose range of values is unknown, the compiler must assume the worst case, leading to non-optimal code: code that calls a subroutine, or code that is inline but branches. By restricting the shift count to the range 0 − 31, the Int64ShllMod32 function lets the compiler generate optimal or near-optimal code.

Please note that the Int64ShllMod32 function's Value parameter and return value are 64-bit values, not LARGE_INTEGER structures.

See Also

Int64ShraMod32, Int64ShrlMod32


Int64ShraMod32

The Int64ShraMod32 function performs a right arithmetic shift operation on a signed 64-bit integer value. The function provides improved shifting code for right arithmetic shifts where the shift count is in the range 0 − 31.

LONGLONG Int64ShraMod32(

LONGLONG  Value,	// specifies signed 64-bit integer to shift right arithmetically
DWORD  ShiftCount	// specifies a shift count in the range 0 − 31
);
Parameters

Value

Specifies the signed 64-bit integer to be shifted.

ShiftCount

Specifies a shift count in the range 0 − 31.

Return Value

The return value is the signed 64-bit integer result of the right arithmetic shift operation.

Remarks

The shift count is the number of bit positions that the value's bits move.

In a right arithmetic shift operation on a signed value, the value's bits move to the right, and vacated bits on the left side of the value are set to the value of the sign bit.

A compiler can generate optimal code for a right arithmetic shift operation when the shift count is a constant. However, if the shift count is a variable whose range of values is unknown, the compiler must assume the worst case, leading to non-optimal code: code that calls a subroutine, or code that is inline but branches. By restricting the shift count to the range 0 − 31, the Int64ShraMod32 function lets the compiler generate optimal or near-optimal code.

Please note that the Int64ShraMod32 function's Value parameter and return value are 64-bit values, not LARGE_INTEGER structures.

See Also

Int64ShllMod32, Int64ShrlMod32


Int64ShrlMod32

The Int64ShrlMod32 function performs a right logical shift operation on an unsigned 64-bit integer value. The function provides improved shifting code for right logical shifts where the shift count is in the range 0 − 31.

DWORDLONG Int64ShrlMod32(

DWORDLONG  Value,	// specifies unsigned 64-bit integer to shift right logically
DWORD  ShiftCount	// specifies a shift count in the range 0 − 31
);
Parameters

Value

Specifies the unsigned 64-bit integer to be shifted.

ShiftCount

Specifies a shift count in the range 0 − 31.

Return Value

The return value is the unsigned 64-bit integer result of the right logical shift operation.

Remarks

The shift count is the number of bit positions that the value's bits move.

In a right logical shift operation on an unsigned value, the value's bits move to the right, and vacated bits on the left side of the value are set to zero.

A compiler can generate optimal code for a right logical shift operation when the shift count is a constant. However, if the shift count is a variable whose range of values is unknown, the compiler must assume the worst case, leading to non-optimal code: code that calls a subroutine, or code that is inline but branches. By restricting the shift count to the range 0 − 31, the Int64ShrlMod32 function lets the compiler generate optimal or near-optimal code.

Please note that the Int64ShrlMod32 function's Value parameter and return value are 64-bit values, not LARGE_INTEGER structures.

See Also

Int64ShllMod32, Int64ShraMod32


InterlockedDecrement

The InterlockedDecrement function both decrements (decreases by one) the value of the specified 32-bit variable and checks the resulting value. The function prevents more than one thread from using the InterlockedDecrement or InterlockedIncrement function to access the same variable simultaneously.

LONG InterlockedDecrement(

LPLONG  lplVal	// address of the variable to decrement
);
Parameters

lplVal

Points to the 32-bit variable to decrement.

Return Value

If the result of the decrement is zero, the return value is zero.

If the result of the decrement is less than zero, the return value is less than zero. If the result of the decrement is greater than zero, the return value is greater than zero. A nonzero return value may not be equal to the result of the decrement.

Remarks

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

The InterlockedExchange function atomically exchanges a pair of 32-bit values.

LONG InterlockedExchange(

LPLONG  Target,	// address of 32-bit value to exchange
LONG  Value	// new value for the LONG value pointed to by Target
);
Parameters

Target

Address of the LONG value to exchange. The function sets this LONG value to Value, and returns its prior value.

Value

Specifies a new value for the LONG value pointed to by Target.

Return Value

The function returns the prior value of the LONG value pointed to by Target.

Remarks

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

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.

LONG InterlockedIncrement(

LPLONG  lplVal	// address of the variable to increment
);
Parameters

lplVal

Points to the 32-bit variable to increment.

Return Value

If the result of the increment is zero, the return value is zero.

If the result of the increment is less than zero, the return value is less than zero. If the result of the increment is greater than zero, the return value is greater than zero. A nonzero return value may not be equal to the result of the increment.

Remarks

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


IntersectClipRect

The IntersectClipRect function creates a new clipping region from the intersection of the current clipping region and the specified rectangle.

int IntersectClipRect(

HDC  hdc,	// handle of device context
int  nLeftRect,	// x-coordinate of upper-left corner of rectangle
int  nTopRect,	// y-coordinate of upper-left corner of rectangle
int  nRightRect,	// x-coordinate of lower-right corner of rectangle
int  nBottomRect	// y-coordinate of lower-right corner of rectangle
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the logical x-coordinate of the upper-left corner of the rectangle.

nTopRect

Specifies the logical y-coordinate of the upper-left corner of the rectangle.

nRightRect

Specifies the logical x-coordinate of the lower-right corner of the rectangle.

nBottomRect

Specifies the logical y-coordinate of the lower-right corner of the rectangle.

Return Value

If the function succeeds, the return value specifies the new clipping region's type and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred. (The current clipping region is unaffected.)
Remarks

The lower and rightmost edges of the given rectangle are excluded from the clipping region.

See Also

ExcludeClipRect


IntersectRect

The IntersectRect function calculates the intersection of two source rectangles and places the coordinates of the intersection rectangle into the destination rectangle. If the source rectangles do not intersect, an empty rectangle (in which all coordinates are set to zero) is placed into the destination rectangle.

BOOL IntersectRect(

LPRECT  lprcDst,	// address of structure for intersection
CONST RECT  *lprcSrc1,	// address of structure with first rectangle
CONST RECT  *lprcSrc2	// address of structure with second rectangle
);
Parameters

lprcDst

Points to the RECT structure that is to receive the intersection of the rectangles pointed to by the lprcSrc1 and lprcSrc2 parameters.

lprcSrc1

Points to the RECT structure that contains the first source rectangle.

lprcSrc2

Points to the RECT structure that contains the second source rectangle.

Return Value

If the rectangles intersect, the return value is TRUE; otherwise, it is FALSE. To get extended error information, call GetLastError.

See Also

InflateRect, OffsetRect, RECT, UnionRect


InvalidateRect

The InvalidateRect function adds a rectangle to the specified window's update region. The update region represents the portion of the window's client area that must be redrawn.

BOOL InvalidateRect(

HWND  hwnd,	// handle of window with changed update region
CONST RECT  *lprc,	// address of rectangle coordinates
BOOL  fErase	// erase-background flag
);
Parameters

hwnd

Identifies the window whose update region has changed. If this parameter is NULL, Windows invalidates and redraws all windows, and sends the WM_ERASEBKGND and WM_NCPAINT messages to the window procedure before the function returns.

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.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The invalidated areas accumulate in the update region until the region is processed when the next WM_PAINT message occurs or until the region is validated by using the ValidateRect or ValidateRgn function.

Windows sends a WM_PAINT message to a window whenever its update region is not empty and there are no other messages in the application queue for that window.

If the 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, RECT, ValidateRect, ValidateRgn, WM_ERASEBKGND, WM_NCPAINT, WM_PAINT,


InvalidateRgn

The InvalidateRgn function invalidates the client area within the specified region by adding it to the current update region of a window. The invalidated region, along with all other areas in the update region, is marked for painting when the next WM_PAINT message occurs.

BOOL InvalidateRgn(

HWND  hwnd,	// handle of window with changed update region
HRGN  hrgn,	// handle of region to add
BOOL  fErase	// erase-background flag
);
Parameters

hwnd

Identifies the window with an update region that is to be modified.

hrgn

Identifies the region to be added to the update region. The region is assumed to have client coordinates. If this parameter is NULL, the entire client area is added to the update region.

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.

Return Value

This function always returns TRUE.

Remarks

Invalidated areas accumulate in the update region until the next WM_PAINT message is processed or until the region is validated by using the ValidateRect or ValidateRgn function.

Windows sends a WM_PAINT message to a window whenever its update region is not empty and there are no other messages in the application queue for that window.

The specified region must have been created by using one of the region functions.

If the fErase parameter is TRUE for any part of the update region, the background in the entire region is erased, not just in the specified part.

See Also

BeginPaint, InvalidateRect, ValidateRect, ValidateRgn, WM_PAINT


InvertRect

The InvertRect function inverts a rectangle in a window by performing a logical NOT operation on the color values for each pixel in the rectangle's interior.

BOOL InvertRect(

HDC  hdc,	// handle of device context
CONST RECT  *lprc	// address of structure with rectangle
);
Parameters

hdc

Identifies the device context.

lprc

Points to a RECT structure that contains the logical coordinates of the rectangle to be inverted.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

On monochrome screens, InvertRect makes white pixels black and black pixels white. On color screens, the inversion depends on how colors are generated for the screen. Calling InvertRect twice for the same rectangle restores the display to its previous colors.

See Also

FillRect, RECT


InvertRgn

The InvertRgn function inverts the colors in the specified region.

BOOL InvertRgn(

HDC  hdc,	// handle of device context
HRGN  hrgn	// handle of region to be inverted
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region for which colors are inverted. The region's coordinates are presumed to be logical coordinates.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

On monochrome screens, the InvertRgn function makes white pixels black and black pixels white. On color screens, this inversion is dependent on the type of technology used to generate the colors for the screen.

See Also

FillRgn, PaintRgn


IOCTL_DISK_CHECK_VERIFY

The IOCTL_DISK_CHECK_VERIFY DeviceIoControl operation determines whether a device's media is accessible; for example, whether the media is in the device.

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

Parameters

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.

Return Value

If the operation succeeds and the device media is accessible, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE.

See Also

DeviceIoControl


IOCTL_DISK_EJECT_MEDIA

The IOCTL_DISK_EJECT_MEDIA DeviceIoControl operation causes media to be ejected from a SCSI device.

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

Parameters

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

IOCTL_DISK_EJECT_MEDIA may or may not be supported on SCSI devices that support removable media.

See Also

DeviceIoControl, IOCTL_DISK_MEDIA_REMOVAL, IOCTL_DISK_LOAD_MEDIA


IOCTL_DISK_FORMAT_TRACKS

The IOCTL_DISK_FORMAT_TRACKS DeviceIoControl operation formats a specified, contiguous set of tracks on a disk.

dwIoControlCode = IOCTL_DISK_FORMAT_TRACKS;   // operation code

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

Parameters

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for floppy disk devices only.

See Also

DeviceIoControl, FORMAT_PARAMETERS


IOCTL_DISK_GET_DRIVE_GEOMETRY

The IOCTL_DISK_GET_DRIVE_GEOMETRY DeviceIoControl operation returns information about the physical disk's geometry: type, number of cylinders, tracks per cylinder, sectors per track, and bytes per sector.

dwIoControlCode = IOCTL_DISK_GET_DRIVE_GEOMETRY;   // operation code

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

Parameters

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices.

See Also

DeviceIoControl, DISK_GEOMETRY, IOCTL_DISK_GET_MEDIA_TYPES


IOCTL_DISK_GET_DRIVE_LAYOUT

The IOCTL_DISK_GET_DRIVE_LAYOUT DeviceIoControl operation returns information about the number of partitions on a disk and the features of each partition.

dwIoControlCode = IOCTL_DISK_GET_DRIVE_LAYOUT;   // operation code

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

Parameters

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 structure and a series of PARTITION_INFORMATION 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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

See Also

DeviceIoControl, DRIVE_LAYOUT_INFORMATION, IOCTL_DISK_SET_DRIVE_LAYOUT, PARTITION_INFORMATION


IOCTL_DISK_GET_MEDIA_TYPES

The IOCTL_DISK_GET_MEDIA_TYPES DeviceIoControl operation returns information about the types of media a device driver supports.

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

Parameters

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 that the driver supports.

lpcbBytesReturned

Points to a DWORD that receives the actual size, in bytes, of the data stored into lpvOutBuffer.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for all class drivers, as well as non-computer system interface (SCSI) hard drives and floppy disk devices.

See Also

DeviceIoControl, DISK_GEOMETRY, IOCTL_DISK_GET_DRIVE_GEOMETRY


IOCTL_DISK_GET_PARTITION_INFO

The IOCTL_DISK_GET_PARTITION_INFO DeviceIoControl operation returns information about the type, size, and nature of a disk partition.

dwIoControlCode = IOCTL_DISK_GET_PARTITION_INFO ;   // operation code

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

Parameters

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, do not need to handle this operation.

See Also

DeviceIoControl, IOCTL_DISK_SET_PARTITION_INFO, PARTITION_INFORMATION


IOCTL_DISK_LOAD_MEDIA

The IOCTL_DISK_LOAD_MEDIA DeviceIoControl operation causes media to be loaded into a device.

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

Parameters

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.

Remarks

The IOCTL_DISK_LOAD_MEDIA is valid only for devices that support loadable media.

See Also

DeviceIoControl, IOCTL_DISK_EJECT_MEDIA, IOCTL_DISK_MEDIA_REMOVAL


IOCTL_DISK_MEDIA_REMOVAL

The IOCTL_DISK_MEDIA_REMOVAL DeviceIoControl operation enables or disables the mechanism that ejects media, for those devices possessing that locking capability.

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

Parameters

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

The IOCTL_DISK_MEDIA_REMOVAL operation is valid only for devices that support removable media.

See Also

DeviceIoControl, IOCTL_DISK_EJECT_MEDIA, IOCTL_DISK_LOAD_MEDIA, PREVENT_MEDIA_REMOVAL


IOCTL_DISK_PERFORMANCE

The IOCTL_DISK_PERFORMANCE DeviceIoControl operation provides disk performance information.

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

Parameters

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices.

See Also

DeviceIoControl, DISK_PERFORMANCE


IOCTL_DISK_REASSIGN_BLOCKS

The IOCTL_DISK_REASSIGN_BLOCKS DeviceIoControl operation directs the disk device to map one or more blocks to its spare-block pool.

dwIoControlCode = IOCTL_DISK_REASSIGN_BLOCKS;   // operation code

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

Parameters

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices.

See Also

DeviceIoControl, REASSIGN_BLOCKS


IOCTL_DISK_SET_DRIVE_LAYOUT

The IOCTL_DISK_SET_DRIVE_LAYOUT DeviceIoControl operation partitions a disk as specified by drive layout and partition information data.

dwIoControlCode = IOCTL_DISK_SET_DRIVE_LAYOUT;   // operation code

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

Parameters

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

See Also

DeviceIoControl, DRIVE_LAYOUT_INFORMATION, IOCTL_DISK_GET_DRIVE_LAYOUT, PARTITION_INFORMATION


IOCTL_DISK_SET_PARTITION_INFO

The IOCTL_DISK_SET_PARTITION_INFO DeviceIoControl operation sets the partition type of the specified disk partition.

dwIoControlCode = IOCTL_DISK_SET_PARTITION_INFO;   // operation code

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

Parameters

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

See Also

DeviceIoControl, IOCTL_DISK_GET_PARTITION_INFO, SET_PARTITION_INFORMATION


IOCTL_DISK_VERIFY

The IOCTL_DISK_VERIFY DeviceIoControl operation performs a logical format of a specified extent on a disk.

dwIoControlCode = IOCTL_DISK_VERIFY;   // operation code

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

Parameters

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

This device I/O control operation is for disk devices. Floppy disk drivers, however, need not handle this operation.

See Also

DeviceIoControl, IOCTL_DISK_CHECK_VERIFY, VERIFY_INFORMATION


IOCTL_SERIAL_LSRMST_INSERT

The IOCTL_SERIAL_LSRMST_INSERT DeviceIoControl operation enables or disables the placement of line status and modem status values into the regular data stream that an application acquires through the ReadFile function.

When this line-status and modem-status data placement mode is enabled, status values are preceded in the data stream by an escape character. The user-definable escape character is set by the IOCTL_SERIAL_LSRMST_INSERT operation. Status values consist of 1 to 3 BYTEs. See the Remarks section below for status value details.

dwIoControlCode = IOCTL_SERIAL_LSRMST_INSERT;     // operation code

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

Parameters

lpvInBuffer

Points to a buffer that contains a single BYTE.

If the BYTE is a nonzero value, it is the desired line-status and modem-status value escape character. The operation will turn the LSRMST_INSERT line-status and modem-status data placement mode on.

If the BYTE is zero, the operation will turn the LSRMST_INSERT line-status and modem-status data placement mode off.

The escape character can not be the XON or XOFF character.

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.

Return Value

If the operation succeeds, DeviceIoControl returns TRUE.

If the operation fails, DeviceIoControl returns FALSE. To get extended error information, call GetLastError.

Remarks

Note that an application that uses this scheme must examine each character in the data stream to determine the presence of modem-status or line-status data.

The following values follow the designated escape character in the data stream if the LSRMST_INSERT mode has been turned on :

Value	Meaning
SERIAL_LSRMST_ESCAPE	Indicates the reception of the escape character itself into the data stream.
SERIAL_LSRMST_LSR_DATA	Indicates that a line status change occurred, and data was available in the receive hardware buffer. Following this BYTE is a BYTE value of the line status register is the BYTE present in the receive hardware buffer when the line status change was processed.
SERIAL_LSRMST_LSR_NODATA	Indicates that a line status change occurred, but no data was available in the receive hardware buffer.
SERIAL_LSRMST_MST	Indicates that a modem status change occurred. Following this BYTE is a BYTE that is the value of the modem status register when the modem status change was processed.
See Also

DeviceIoControl, ReadFile


ioctlsocket

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

int ioctlsocket (

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

s

A descriptor identifying a socket.

cmd

The command to perform on the socket s.

argp

A pointer to a parameter for cmd.

Return Value

If the function succeeds, ioctlsocket returns zero.

If the function fails, a value of SOCKET_ERROR is returned. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINVAL	The cmd parameter is not valid, or argp is not an acceptable parameter for cmd, or the command is not applicable to the type of socket supplied.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAENOTSOCK	The descriptor s is not a socket.
Remarks

This function may be used on any socket in any state. It is used to get or set operating parameters associated with the socket, independent of the protocol and communications subsystem. The following commands are supported:

Command	Semantics
FIONBIO	Enable or disable nonblocking mode on the socket s. argp points at an unsigned long, which is nonzero if nonblocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (that is, nonblocking mode is disabled). This is consistent with BSD sockets.
	The WSAAsyncSelect function automatically sets a socket to nonblocking mode. If WSAAsyncSelect has been issued on a socket, then any attempt to use ioctlsocket to set the socket back to blocking mode will fail with WSAEINVAL. To set the socket back to blocking mode, an application must first disable WSAAsyncSelect by calling WSAAsyncSelect with the lEvent parameter equal to zero.
FIONREAD	Determine the amount of data that can be read atomically from socket s. argp points at an unsigned long in which ioctlsocket stores the result. If s is of type SOCK_STREAM, FIONREAD returns the total amount of data that can be read in a single recv; this is normally the same as the total amount of data queued on the socket. If s is of type SOCK_DGRAM, FIONREAD returns the size of the first datagram queued on the socket.
SIOCATMARK	Determine whether all out-of-band data has been read. This applies only to a socket of type SOCK_STREAM that has been configured for in-line reception of any out-of-band data (SO_OOBINLINE). If no out-of-band data is waiting to be read, the operation returns TRUE. Otherwise, it returns FALSE, and the next recv or recvfrom performed on the socket will retrieve some or all of the data preceding the "mark"; the application should use the SIOCATMARK operation to determine whether any data remains. If there is any normal data preceding the "urgent" (out-of-band) data, it will be received in order. (Note that a recv or recvfrom will never mix out-of-band and normal data in the same call.) argp points at a BOOL in which ioctlsocket stores the result.
Compatibility

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

See Also

getsockopt, socket, setsockopt, WSAAsyncSelect, WSAStartup


IsBadCodePtr

The IsBadCodePtr function determines whether the calling process has read access to the memory at the specified address.

BOOL IsBadCodePtr(

FARPROC  lpfnProc	// address of function
);
Parameters

lpfnProc

Points to an address in memory.

Return Value

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, call GetLastError.

Remarks

IsBadCodePtr checks the read access only at the specified address and does not guarantee read access to a range of memory.

In a preemptive multitasking environment, it is possible for some other thread to change the process's access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadReadPtr, IsBadStringPtr, IsBadWritePtr


IsBadHugeReadPtr

The IsBadHugeReadPtr function verifies that the calling process has read access to the specified range of memory.

BOOL IsBadHugeReadPtr(

CONST VOID  *lpvPtr,	// address of memory block
UINT  cbBytes	// size of block
);
Parameters

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.

Return Value

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, call GetLastError.

Remarks

If the calling process has read access to some, but not all, of the bytes in the specified memory range, the return value is TRUE.

In a preemptive multitasking environment, it is possible for some other thread to change the process's access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

IsBadHugeReadPtr is available for compatibility with earlier versions of Windows that distinguish between normal memory allocations and huge allocations occupying multiple segments. In the Win32 API, this function is equivalent to the IsBadReadPtr function.

See Also

IsBadHugeWritePtr, IsBadReadPtr, IsBadStringPtr, IsBadWritePtr


IsBadHugeWritePtr

The IsBadHugeWritePtr function verifies that the calling process has write access to the specified range of memory.

BOOL IsBadHugeWritePtr(

LPVOID  lpvPtr,	// address of memory block
UINT  cbBytes	// size of block
);
Parameters

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.

Return Value

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, call GetLastError.

Remarks

If the calling process has write access to some, but not all, of the bytes in the specified memory range, the return value is TRUE.

In a preemptive multitasking environment, it is possible for some other thread to change the process's access to the memory being tested. Even when the function indicates that the process has write access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

IsBadHugeWritePtr is available for compatibility with earlier versions of Windows, which distinguish between normal memory allocations and huge allocations occupying multiple segments. In the Win32 API, this function is equivalent to the IsBadWritePtr function.

See Also

IsBadHugeReadPtr, IsBadReadPtr, IsBadStringPtr, IsBadWritePtr


IsBadReadPtr

The IsBadReadPtr function verifies that the calling process has read access to the specified range of memory.

BOOL IsBadReadPtr(

CONST VOID  *lpvPtr,	// address of memory block
UINT  cbBytes	// size of block
);
Parameters

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.

Return Value

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, call GetLastError.

Remarks

If the calling process has read access to some, but not all, of the bytes in the specified memory range, the return value is TRUE.

In a preemptive multitasking environment, it is possible for some other thread to change the process's access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadStringPtr, IsBadWritePtr


IsBadStringPtr

The IsBadStringPtr function verifies that the calling process has read access to a range of memory pointed to by a string pointer.

BOOL IsBadStringPtr(

LPCTSTR  lpszStr,	// address of string
UINT  cchMax	// maximum size of string
);
Parameters

lpszStr

Points to a null-terminated string, either Unicode or ASCII.

cchMax

Specifies the maximum size, in characters, of the string. The function checks for read access in all bytes up to the string's terminating null character or up to the number of bytes specified by this parameter, whichever is smaller. If this parameter is zero, the return value is FALSE.

Return Value

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, call GetLastError.

Remarks

If the calling process has read access to some, but not all, of the bytes in the specified memory range, the return value is TRUE.

In a preemptive multitasking environment, it is possible for some other thread to change the process's access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadCodePtr, IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadReadPtr, IsBadWritePtr


IsBadWritePtr

The IsBadWritePtr function verifies that the calling process has write access to the specified range of memory.

BOOL IsBadWritePtr(

LPVOID  lpvPtr,	// address of memory block
UINT  cbBytes	// size of block
);
Parameters

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.

Return Value

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, call GetLastError.

Remarks

If the calling process has write access to some, but not all, of the bytes in the specified memory range, the return value is TRUE.

In a preemptive multitasking environment, it is possible for some other thread to change the process's access to the memory being tested. Even when the function indicates that the process has write access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

See Also

IsBadCodePtr, IsBadHugeReadPtr, IsBadHugeWritePtr, IsBadReadPtr


IsCharAlpha

The IsCharAlpha function determines whether a character is an alphabetic character. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

BOOL IsCharAlpha(

TCHAR  ch	// character to test
);
Parameters

ch

Specifies the character to be tested.

Return Value

If the character is alphabetic, the return value is TRUE.

If the character is not alphabetic, the return value is FALSE.

To get extended error information, call GetLastError.

See Also

IsCharAlphaNumeric


IsCharAlphaNumeric

The IsCharAlphaNumeric function determines whether a character is either an alphabetic or a numeric character. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

BOOL IsCharAlphaNumeric(

TCHAR  ch	// character to test
);
Parameters

ch

Specifies the character to be tested.

Return Value

If the character is alphanumeric, the return value is TRUE.

If the character is not alphanumeric, the return value is FALSE.

To get extended error information, call GetLastError.

See Also

IsCharAlpha


IsCharLower

The IsCharLower function determines whether a character is lowercase. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

BOOL IsCharLower(

TCHAR  ch	// character to test
);
Parameters

ch

Specifies the character to be tested.

Return Value

If the character is lowercase, the return value is TRUE.

If the character is not lowercase, the return value is FALSE.

To get extended error information, call GetLastError.

See Also

IsCharUpper


IsCharUpper

The IsCharUpper function determines whether a character is uppercase. This determination is based on the semantics of the language selected by the user during setup or by using Control Panel.

BOOL IsCharUpper(

TCHAR  ch	// character to test
);
Parameters

ch

Specifies the character to be tested.

Return Value

If the character is uppercase, the return value is TRUE.

If the character is not uppercase, the return value is FALSE.

To get extended error information, call GetLastError.

See Also

IsCharLower


IsChild

The IsChild function tests whether a window is a child window or descendant window of a specified parent window. A child window is the direct descendant of a specified parent window if that parent window is in the chain of parent windows; the chain of parent windows leads from the original overlapped or pop-up window to the child window.

BOOL IsChild(

HWND  hwndParent,	// handle of parent window
HWND  hwnd	// handle of window to test
);
Parameters

hwndParent

Identifies the parent window.

hwnd

Identifies the window to be tested.

Return Value

If the window is a child or descendant window of the specified parent window, the return value is TRUE.

If the window is not a child or descendant window of the specified parent window, the return value is FALSE.

See Also

IsWindow, SetParent


IsClipboardFormatAvailable

The IsClipboardFormatAvailable function determines whether the clipboard contains data in the specified format.

BOOL IsClipboardFormatAvailable(

UINT  uFormat	// clipboard format
);
Parameters

uFormat

Specifies a standard or registered clipboard format. For a description of the clipboard formats, see the SetClipboardData function.

Return Value

If the clipboard format is available, the return value is TRUE.

If the clipboard is not available, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

Typically, an application that recognizes only one clipboard format would call this function when processing the WM_INITMENU or WM_INITMENUPOPUP message. The application would then enable or disable the Paste menu item, depending on the return value. Applications that recognize more than one clipboard format should use the GetPriorityClipboardFormat function for this purpose.

See Also

CountClipboardFormats, EnumClipboardFormats, GetPriorityClipboardFormat, RegisterClipboardFormat, SetClipboardData, WM_INITMENU, WM_INITMENUPOPUP


IsDBCSLeadByte

The IsDBCSLeadByte function determines whether a character is a lead byte — that is, the first byte of a character in a double-byte character set (DBCS).

BOOL IsDBCSLeadByte(

BYTE  bTestChar	// character to test
);
Parameters

bTestChar

Specifies the character to be tested.

Return Value

If the character is a lead byte, the return value is TRUE.

If the character is not a lead byte, the return value is FALSE.

To get extended error information, call GetLastError.

Remarks

Lead bytes are unique to double-byte character sets. A lead byte introduces a double-byte character. Lead bytes occupy a specific range of byte values. The IsDBCSLeadByte function uses the ANSI code page to check lead-byte ranges.

See Also

MultiByteToWideChar


IsDBCSLeadByteEx  (preliminaryWindows NT)
IsDBCSLeadByteEx  (preliminary−Windows NT)

The IsDBCSLeadByteEx function determines whether a character is a lead byte — that is, the first byte of a character in a double-byte character set (DBCS).

BOOL IsDBCSLeadByteEx(

UINT  CodePage,	// identifier of code page
BYTE  TestChar	// character to test
);
Parameters

CodePage

Identifier of the code page to use to check lead-byte ranges. Can be one of the following predefined values:

Value	Meaning
0	Use system default ANSI code page.
CP_ACP	Use system default ANSI code page.
CP_OEMCP	Use system default OEM code page.
TestChar

Character to test.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


IsDialogMessage

The IsDialogMessage function determines whether a message is intended for the specified dialog box and, if it is, processes the message.

BOOL IsDialogMessage(

HWND  hwndDlg,	// handle of dialog box
LPMSG  lpmsg	// address of structure with message
);
Parameters

hwndDlg

Identifies the dialog box.

lpmsg

Points to an MSG structure that contains the message to be checked.

Return Value

If the message has been processed, the return value is TRUE.

If the message has not been processed, the return value is FALSE.

Remarks

Although the IsDialogMessage function is intended for modeless dialog boxes, you can use it with any window that contains controls, enabling the windows to provide the same keyboard selection as is used in a dialog box.

When IsDialogMessage processes a message, it checks for keyboard messages and converts them into selection commands for the corresponding dialog box. For example, the TAB key, when pressed, selects the next control or group of controls, and the DOWN ARROW key, when pressed, selects the next control in a group.

Because the IsDialogMessage function performs all necessary translating and dispatching of messages, a message processed by IsDialogMessage must not be passed to the TranslateMessage or DispatchMessage function.

IsDialogMessage sends WM_GETDLGCODE messages to the dialog box procedure to determine which keys should be processed.

IsDialogMessage can send DM_GETDEFID and DM_SETDEFID messages to the window. These messages are defined in the WINUSER.H header file as WM_USER and WM_USER + 1, so conflicts are possible with application-defined messages having the same values.

See Also

DispatchMessage, DM_GETDEFID, DM_SETDEFID, MSG, TranslateMessage, WM_GETDLGCODE, WM_USER


IsDlgButtonChecked

The IsDlgButtonChecked function determines whether a button control has a check mark next to it or whether a three-state button control is grayed, checked, or neither.

UINT IsDlgButtonChecked(

HWND  hwndDlg,	// handle of dialog box
int  idButton	// button identifier
);
Parameters

hwndDlg

Identifies the dialog box that contains the button control.

idButton

Specifies the integer identifier of the button control.

Return Value

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 is unchecked. Same as the Windows 95 constant BST_UNCHECKED.
1	Button is checked. Same as the Windows 95 constant BST_CHECKED.
2	Button is grayed, indicating an indeterminate state (applies only if the button has the BS_3STATE or BS_AUTO3STATE style). Same as the Windows 95 constant BST_INDETERMINATE.
BST_CHECKED	Windows 95 only: Button is checked.
BST_INDETERMINATE	Windows 95 only: Button is grayed, indicating an indeterminate state (applies only if the button has the BS_3STATE or BS_AUTO3STATE style).
BST_UNCHECKED	Windows 95 only: Button is unchecked
If the button has any other style, the return value is zero.

Remarks

The IsDlgButtonChecked function sends a BM_GETCHECK message to the specified button control.

See Also

CheckDlgButton


IsIconic

The IsIconic function determines whether the specified window is minimized (iconic).

BOOL IsIconic(

HWND  hwnd	// handle of window
);
Parameters

hwnd

Identifies the window.

Return Value

If the window is iconic, the return value is TRUE.

If the is not iconic, the return value is FALSE.

See Also

IsZoomed


IsMenu

The IsMenu function determines whether a handle is a menu handle.

BOOL IsMenu(

HMENU  hMenu	// handle to test
);
Parameters

hMenu

The handle to be tested.

Return Value

If hMenu is a menu handle, the function returns TRUE; if it is not, the function returns FALSE.


IsRectEmpty

The IsRectEmpty function determines whether the specified rectangle is empty. A empty rectangle is one that has no area; that is, the coordinate of the right side is less than or equal to the coordinate of the left side, or the coordinate of the bottom side is less than or equal to the coordinate of the top side.

BOOL IsRectEmpty(

CONST RECT  *lprc	// address of structure with rectangle
);
Parameters

lprc

Points to a RECT structure that contains the logical coordinates of the rectangle.

Return Value

If the rectangle is empty, the return value is TRUE; otherwise, it is FALSE. To get extended error information, call GetLastError.

See Also

EqualRect, PtInRect, RECT


IsTask

The IsTask function is not implemented in the WIn32 API.


IsTextUnicode

The IsTextUnicode function determines whether a buffer probably contains a form of Unicode text. The function uses various statistical and deterministic methods to make its determination, under the control of flags passed via lpResult. When the function returns, the results of such tests are reported via lpResult. If all specified tests are passed, the function returns TRUE; otherwise, it returns FALSE.

DWORD IsTextUnicode(

CONST LPVOID  lpvBuffer,	// pointer to an input buffer to be examined
int  cb,	// the size in bytes of the input buffer
LPINT  lpResult	// pointer to flags that condition text examination and receive results
);
Parameters

lpvBuffer

Pointer to the input buffer to be examined.

cb

Specifies the size, in bytes, of the input buffer pointed to by lpvBuffer.

lpResult

Pointer to an int that, upon entry to the function, contains a set of flags that specify the tests to be applied to the input buffer text. Upon exit from the function, that same int contains a set of bit flags indicating the results of the specified tests: 1 if the contents of the buffer pass a test, 0 for failure. Only flags that are set upon entry to the function are significant upon exit.

If lpResult is NULL, the function uses all available tests to determine whether the data in the buffer is probably Unicode text.

Here are the constants used with *lpResult's bit flags:

Value	Meaning
IS_TEXT_UNICODE_ASCII16	The text is Unicode, and contains nothing but zero-extended ASCII values/characters.
IS_TEXT_UNICODE_REVERSE_ASCII16	Same as the preceding, except that the Unicode text is byte-reversed.
IS_TEXT_UNICODE_STATISTICS	The text is probably Unicode, with the determination made by applying statistical analysis. Absolute certainty is not guaranteed. See the note in the following Remarks section.
IS_TEXT_UNICODE_REVERSE_STATISTICS	Same as the preceding, except that the probably-Unicode text is byte-reversed.
IS_TEXT_UNICODE_CONTROLS	The text contains Unicode representations of one or more of these non-printing characters: RETURN, LINEFEED, SPACE, CJK_SPACE, TAB.
IS_TEXT_UNICODE_REVERSE_CONTROLS	Same as the preceding, except that the Unicode characters are byte-reversed.
IS_TEXT_UNICODE_BUFFER_TOO_SMALL	There are too few characters in the buffer for meaningful analysis (fewer than two bytes).
IS_TEXT_UNICODE_SIGNATURE	The text contains the Unicode byte-order mark (BOM) 0xFEFF as its first character.
IS_TEXT_UNICODE_REVERSE_SIGNATURE	The text contains the Unicode byte-reversed byte-order mark (Reverse BOM) 0xFFFE as its first character.
IS_TEXT_UNICODE_ILLEGAL_CHARS	The text contains one of these Unicode-illegal characters: embedded Reverse BOM, UNICODE_NUL, CRLF (packed into one WORD), or 0xFFFF.
IS_TEXT_UNICODE_ODD_LENGTH	The number of characters in the string is odd. A string of odd length cannot (by definition) be Unicode text.
IS_TEXT_UNICODE_NULL_BYTES	The text contains null bytes, which indicate non-ASCII text.
IS_TEXT_UNICODE_UNICODE_MASK	This flag constant is a combination of IS_TEXT_UNICODE_ASCII16, IS_TEXT_UNICODE_STATISTICS, IS_TEXT_UNICODE_CONTROLS, IS_TEXT_UNICODE_SIGNATURE.
IS_TEXT_UNICODE_REVERSE_MASK	This flag constant is a combination of IS_TEXT_UNICODE_REVERSE_ASCII16, IS_TEXT_UNICODE_REVERSE_STATISTICS, IS_TEXT_UNICODE_REVERSE_CONTROLS, IS_TEXT_UNICODE_REVERSE_SIGNATURE.
IS_TEXT_UNICODE_NOT_UNICODE_MASK	This flag constant is a combination of IS_TEXT_UNICODE_ILLEGAL_CHARS, IS_TEXT_UNICODE_ODD_LENGTH, and two currently unused bit flags.
IS_TEXT_UNICODE_NOT_ASCII_MASK	This flag constant is a combination of IS_TEXT_UNICODE_NULL_BYTES and three currently unused bit flags.
Return Value

The function returns TRUE if the data in the buffer passes the specified tests.

The function returns FALSE if the data in the buffer does not pass the specified tests.

In either case, the int pointed to by lpResult contains the results of the specific tests the function applied to make its determination.

Remarks

As noted in the preceding table of flag constants, the IS_TEXT_UNICODE_STATISTICS and IS_TEXT_UNICODE_REVERSE_STATISTICS tests use statistical analysis. These tests are not foolproof. The statistical tests assume certain amounts of variation between low and high bytes in a string, and some ASCII strings can slip through. For example, if lpvBuffer points to the ASCII string 0x41, 0x0A, 0x0D, 0x1D (A\n\r^Z), the string passes the IS_TEXT_UNICODE_STATISTICS test, though failure would be preferable.


IsValidAcl

The IsValidAcl function validates an access-control list (ACL).

BOOL IsValidAcl(

PACL  pAcl	// address of access-control list
);
Parameters

pAcl

Points to an ACL structure validated by this function. This must be a non-NULL value.

Return Value

If the ACL is valid, the return value is TRUE.

If the ACL is not valid, the return value is FALSE.

To get extended error information, call GetLastError.

Remarks

This function checks the revision level of the ACL and verifies that the number of access-control entries (ACEs) specified in the AceCount member of the ACL structure fits the space specified by the AclSize member of the ACL structure.

If pAcl is NULL, the application will fail with an access violation.

See Also

ACL, GetAclInformation, InitializeAcl


IsValidCodePage

The IsValidCodePage determines whether a specified code page is valid.

BOOL IsValidCodePage(

UINT  CodePage	// specifies code page to check
);
Parameters

CodePage

Specifies the code page to check. Each code page is identified by a unique number.

Return Value

If the code page is valid, the return value is TRUE.

If the code page is not valid, the return value is FALSE.

To get extended error information, call GetLastError.

Remarks

A code page is considered valid only if it is installed in the system.

Following are the code-page identifiers:

Identifier	Meaning
037	EBCDIC
437	MS-DOS  United States
500	EBCDIC "500V1"
708	Arabic (ASMO 708)
709	Arabic (ASMO 449+, BCON V4)
710	Arabic (Transparent Arabic)
720	Arabic (Transparent ASMO)
737	Greek (formerly 437G)
775	Baltic
850	MS-DOS  Multilingual (Latin I)
852	MS-DOS  Slavic (Latin II)
855	IBM Cyrillic (primarily Russian)
857	IBM Turkish
860	MS-DOS  Portuguese
861	MS-DOS Icelandic
862	Hebrew
863	MS-DOS Canadian-French
864	Arabic
865	MS-DOS Nordic
866	MS-DOS Russian
869	IBM Modern Greek
874	Thai
875	EBCDIC
932	Japan
936	Chinese (PRC, Singapore)
949	Korean
950	Chinese (Taiwan, Hong Kong)
1026	EBCDIC
1200	Unicode (BMP of ISO 10646)
1250	Windows 3.1 Eastern European
1251	Windows 3.1 Cyrillic
1252	Windows 3.1 US (ANSI)
1253	Windows 3.1 Greek
1254	Windows 3.1 Turkish
1255	Hebrew
1256	Arabic
1257	Baltic
1361	Korean (Johab)
10000	Macintosh Roman
10001	Macintosh Japanese
10006	Macintosh Greek I
10007	Macintosh Cyrillic
10029	Macintosh Latin 2
10079	Macintosh Icelandic
10081	Macintosh Turkish
See Also

GetACP, GetCPInfo, GetOEMCP


IsValidLocale

The IsValidLocale function applies a validity test to a locale identifier. The dwFlags parameter determines the nature of the validity test. Currently, the function tests whether a locale identifier is installed or supported on the calling system.

BOOL IsValidLocale(

LCID  Locale	// locale indentifier to validate
DWORD  dwFlags	// specifies validity test
);
Parameters

Locale

Specifies the locale identifier to be validated. You can use the MAKELCID macro to create a locale identifier.

dwFlags

Specifies the validity test to apply to the locale identifier. This parameter can be one of the following values:

Value	Meaning
LCID_INSTALLED	Test whether the locale identifier is both supported and installed.
LCID_SUPPORTED	Test whether the locale identifier is supported.
Return Value

If the locale identifier passes the specified validity test, the return value is TRUE.

If the locale identifier does not pass the specified validity test, the return value is FALSE.

Remarks

If the LCID_INSTALLED flag is specified and this function returns TRUE, the locale identifier is both supported and installed on the system.

If the LCID_SUPPORTED flag is specified and this function returns TRUE, the locale identifier is supported in the release, but not necessarily installed on the system.

See Also

GetLocaleInfo


IsValidSecurityDescriptor

The IsValidSecurityDescriptor function validates a SECURITY_DESCRIPTOR structure. Validation is performed by checking the revision level of each component in the security descriptor.

BOOL IsValidSecurityDescriptor(

PSECURITY_DESCRIPTOR  psd	// address of security descriptor
);
Parameters

psd

Points to a SECURITY_DESCRIPTOR structure that the function validates.

Return Value

If the structure of the security descriptor is valid, the return value is TRUE.

If the structure of the security descriptor is not valid, the return value is FALSE. To get extended error information, call GetLastError.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, InitializeSecurityDescriptor, SECURITY_DESCRIPTOR, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl


IsValidSid

The IsValidSid function validates a SID structure by verifying that the revision number is within a known range and that the number of subauthorities is less than the maximum. A SID is a security identifier.

BOOL IsValidSid(

PSID  psid	// address of SID to query
);
Parameters

psid

Points to the SID structure to validate. This must be a non-NULL value.

Return Value

If the SID structure is valid, the return value is TRUE.

If the SID structure is not valid, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

If psid is NULL, the application will fail with an access violation.

See Also

GetLengthSid, GetSidIdentifierAuthority, GetSidLengthRequired, GetSidSubAuthority, GetSidSubAuthorityCount, SID


IsWindow

The IsWindow function determines whether the specified window handle identifies an existing window.

BOOL IsWindow(

HWND  hwnd	// handle of window
);
Parameters

hwnd

Specifies the window handle.

Return Value

If the window handle identifies an existing window, the return value is TRUE; otherwise, it is FALSE.

See Also

IsWindowEnabled, IsWindowVisible


IsWindowEnabled

The IsWindowEnabled function determines whether the specified window is enabled for mouse and keyboard input.

BOOL IsWindowEnabled(

HWND  hwnd	// handle of window to test
);
Parameters

hwnd

Identifies the window to test.

Return Value

If the window is enabled, the return value is TRUE; otherwise, it is FALSE.

Remarks

A child window receives input only if it is both enabled and visible.

See Also

EnableWindow, IsWindowVisible


IsWindowUnicode

The IsWindowUnicode function determines whether the specified window is a native Unicode window.

BOOL IsWindowUnicode(

HWND  hwnd	// handle of window
);
Parameters

hwnd

Identifies the window.

Return Value

If the window is a native Unicode window, the return value is TRUE.

If the window is not a native Unicode window, the return value is FALSE.

Remarks

The system does automatic two-way translation (Unicode to ANSI-ASCII) for window messages. For example, if an ANSI-ASCII window message is sent to a Unicode window, the system translates that message into a Unicode message before calling the window procedure. The system calls the IsWindowUnicode function to determine whether to translate the message.

When this function returns FALSE, the window is a native ANSI-ASCII window.


IsWindowVisible

The IsWindowVisible function retrieves the visibility state of the specified window.

BOOL IsWindowVisible(

HWND  hwnd	// handle of window
);
Parameters

hwnd

Identifies the window.

Return Value

If the specified 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.

Remarks

The visibility state of a window is indicated by the WS_VISIBLE style bit. When WS_VISIBLE is set, the window is displayed and subsequent drawing into it is displayed as long as the window has the WS_VISIBLE style.

Any drawing to a window with the WS_VISIBLE style will not be displayed if the window is obscured by other windows or is clipped by its parent window.

See Also

ShowWindow


IsZoomed

The IsZoomed function determines whether a window is maximized.

BOOL IsZoomed(

HWND  hwnd	// handle of window
);
Parameters

hwnd

Identifies the window.

Return Value

If the window is zoomed, the return value is TRUE.

If the window is not zoomed, the return value is FALSE.

See Also

IsIconic


JournalPlaybackProc

The JournalPlaybackProc hook procedure is a callback function that inserts mouse and keyboard messages into the system message queue. Typically, an application uses this hook procedure to play back a series of mouse and keyboard messages recorded previously by the JournalRecordProc hook procedure. As long as a JournalPlaybackProc hook procedure is installed, regular mouse and keyboard input is disabled.

LRESULT CALLBACK JournalPlaybackProc(

int  nCode,	// hook code
WPARAM  wParam,	// undefined
LPARAM  lParam	// address of message being processed
);
Parameters

nCode

Specifies a code the hook procedure uses to determine how to process the message. This parameter can be one of the following values:

Value	Meaning
HC_GETNEXT	The hook procedure must copy the current mouse or keyboard message to the EVENTMSG structure pointed to by the lParam parameter.
HC_SKIP	The hook procedure must prepare to copy the next mouse or keyboard message to the EVENTMSG structure pointed to by lParam. Upon receiving the HC_GETNEXT code, the hook procedure must copy the message to the structure.
HC_SYSMODALOFF	A system-modal dialog box has been destroyed. The hook procedure must resume playing back the messages.
HC_SYSMODALON	A system-modal dialog box is being displayed. Until the dialog box is destroyed, the hook procedure must stop playing back messages.
If 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.

Return Value

To have the system wait before processing the message, the return value must be the amount of time, in clock ticks, that the system should wait. (This value can be computed by calculating the difference between the time members in the current and previous input messages.) To process the message immediately, the return value should be zero. The return value is used only if the hook code is HC_GETNEXT; otherwise, it is ignored.

Remarks

A JournalPlaybackProc hook procedure should copy an input message to the lParam parameter. The message must have been previously recorded by using a JournalRecordProc hook procedure, which should not modify the message.

To retrieve the same message over and over, the hook procedure can be called several times with the 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 Ctrl+Alt+Del during journal playback, the system stops the playback, unhooks the journal playback procedure, and posts a WM_CANCELJOURNAL message to the journaling application.

If the hook procedure returns a message in the range WM_KEYFIRST to WM_KEYLAST, the following conditions apply:

•	The paramL member of the EVENTMSG structure specifies the virtual key code of the key that was pressed.

•	The paramH member of the EVENTMSG structure specifies the scan code.

•	There's no way to specify a repeast count. The event is always taken to represent one key event.

JournalPlaybackProc is a placeholder for an application-defined or library-defined function name.

See Also

CallNextHookEx, EVENTMSG, JournalRecordProc, SetWindowsHookEx, WM_CANCELJOURNAL


JournalRecordProc

The JournalRecordProc hook procedure is a callback function that records messages the system removes from the system message queue. Later, an application can use a JournalPlaybackProc hook procedure to play back the messages.

LRESULT CALLBACK JournalRecordProc(

int  nCode,	// hook code
WPARAM  wParam,	// undefined
LPARAM  lParam	// address of message being processed
);
Parameters

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

Return Value

The return value is ignored.

Remarks

A JournalRecordProc hook procedure must copy but not modify the messages. After the hook procedure returns control to the system, the message continues to be processed.

An application installs a JournalRecordProc hook procedure by specifying the WH_JOURNALRECORD hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

A Win32 JournalRecordProc hook procedure does not need to live in a dynamic-link library. A Win32 JournalRecordProc hook procedure can live in the application itself.

Unlike most other global hook procedures, the JournalRecordProc and JournalPlaybackProc hook procedures are always called in the context of the thread that set the hook.

An application that has installed a JournalRecordProc hook procedure should watch for the VK_CANCEL virtual keycode (which is implemented as the Ctrl+BREAK key combination on most keyboards). This virtual keycode should be interpreted by the application as a signal that the user wishes to stop journal recording. The application should respond by ending the recording sequence and removing the JournalRecordProc hook procedure. Removal is important. It prevents a journaling application from locking up the system by hanging inside a hook procedure.

This role as a signal to stop journal recording means that a Ctrl+BREAK key combination cannot itself be recorded. Since the Ctrl+C key combination has no such role as a journaling signal, it can be recorded. There are three other key combinations that cannot be recorded: Ctrl+Escape, Alt+Escape, and Ctrl+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, EVENTMSG, JournalPlaybackProc, SetWindowsHookEx, WM_CANCELJOURNAL


keybd_event

The keybd_event function synthesizes a keystroke. The system can use such a synthesized keystroke to generate a WM_KEYUP or WM_KEYDOWN message. The keyboard driver's interrupt handler calls the keybd_event function.

VOID keybd_event(

BYTE  bVirtualKey,	// virtual-key code
BYTE  bScanCode,	// hardware scan code
DWORD  dwFlags,	// flags specifying various function options
DWORD  dwExtraInfo	// additional data associated with keystroke
);
Parameters

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 (224).
KEYEVENTF_KEYUP	If specified, the key is being released. If not specified, the key is being depressed.
dwExtraInfo

Specifies an additional 32-bit value associated with the key stroke.

Return Value

This function has no return value.

Remarks

Although keybd_event passes an OEM-dependent hardware scan code to Windows, applications should not use the scan code. Windows converts scan codes to virtual-key codes internally and clears the up/down bit in the scan code before passing it to applications.

An application can simulate a press of the PRINTSCREEN key in order to obtain a screen snapshot and save it to the Windows clipboard. To do this, call keybd_event with the bVirtualKey parameter set to VK_SNAPSHOT, and the bScanCode parameter set to 0 for a snapshot of the full screen or set bScanCode to 1 for a snapshot of the active window.

See Also

GetAsyncKeyState, GetKeyState, MapVirtualKey, SetKeyboardState


KeyboardProc

The KeyboardProc hook procedure is an application-defined or library-defined callback function the system calls whenever an application calls the GetMessage or PeekMessage function and there is a keyboard message (WM_KEYUP or WM_KEYDOWN) to be processed.

LRESULT CALLBACK KeyboardProc(

int  nCode,	// hook code
WPARAM  wParam,	// virtual-key code
LPARAM  lParam	// keystroke-message information
);
Parameters

nCode

Specifies a code the hook procedure uses to determine how to process the message. This parameter can be one of the following values:

Value	Meaning
HC_ACTION	The wParam and lParam parameters contain information about a 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.
Return Value

To prevent Windows from passing the message to the rest of the hook chain or to the target window procedure, the return value must be a nonzero value. To allow Windows to pass the message to the target window procedure, bypassing the remaining procedures in the chain, the return value must be zero.

Remarks

An application installs the hook procedure by specifying the WH_KEYBOARD hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

KeyboardProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, GetMessage, PeekMessage, SetWindowsHookEx, WM_KEYUP, WM_KEYDOWN


KillTimer

The KillTimer function destroys the specified timer. The system searches the message queue for any pending WM_TIMER messages associated with the timer and removes them.

BOOL KillTimer(

HWND  hwnd,	// handle of window that installed timer
UINT  idEvent	// timer identifier
);
Parameters

hwnd

Identifies the window associated with the specified timer. This value must be the same as the hwnd value passed to the SetTimer function that created the timer.

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

SetTimer, WM_TIMER


LBItemFromPt  (preliminaryWindows NT)
LBItemFromPt  (preliminary−Windows NT)

The LBItemFromPt function retrieves the index of the item at the specified point in a list box.

int LBItemFromPt(

HWND  hLB,
POINT  pt,
BOOL  bAutoScroll
);
Parameters

hLB

Handle to the list box to check.

pt

POINT structure that contains the screen coordinates to check.

bAutoScroll

Scroll flag. If this parameter is TRUE and the point is directly above or below the list box, the function scrolls the list box by one line and returns  − 1. Otherwise, the function does not scroll the list box.

Return Value

The return value is the item identifier if the point is over a list item, or  − 1 otherwise.

Remarks

The LBItemFromPt function only scrolls the list box if a minimum amount of time has passed since it last did so. Timing prevents the list box from scrolling too quickly if the function is called repeatedly in rapid succession — for example, when DL_DRAGGING notification messages or WM_MOUSEMOVE messages are processed.

If the specified point is outside the client area of the list box and bAutoScroll is TRUE, the function scrolls the list box instead of returning an item identifier.

See Also

DL_DRAGGING, POINT, WM_MOUSEMOVE


LCMapString

The LCMapString function maps one character string to another, performing a specified locale-dependent transformation. The function can also be used to generate a sort key for the input string.

int LCMapString(

LCID  lcid,	// locale identifier
DWORD  dwMapFlags,	// mapping transformation type
LPCTSTR  lpSrcStr,	// address of source string
int  cchSrc,	// number of characters in source string
LPTSTR  lpDestStr,	// address of destination buffer
int  cchDest	// size of destination buffer
);
Parameters

lcid

Specifies a locale identifier. The locale provides a context for the string mapping or sort key generation. An application can use the MAKELCID macro to create a locale identifier.

dwMapFlags

A set of flags that indicate the type of transformation to be used during string mapping or sort key generation. An application can specify more than one of these options on a single transformation, although some combinations are illegal. The following mapping options are defined; restrictions are noted following the table:

Option	Meaning
LCMAP_BYTEREV	Windows NT only: Use byte reversal. For example, if you pass in 0x3450 0x4822 the result is 0x5034 0x2248.
LCMAP_FULLWIDTH	Map single-byte characters to double-byte characters.
LCMAP_HALFWIDTH	Map double-byte characters to single-byte characters.
LCMAP_HIRAGANA	Map double-byte Katakana characters to double-byte Hiragana characters.
LCMAP_KATAKANA	Map double-byte Hiragana characters to double-byte Katakana characters.
LCMAP_LOWERCASE	Use lowercase.
LCMAP_SORTKEY	Produce a normalized wide-character sort key.
LCMAP_UPPERCASE	Use uppercase.
NORM_IGNORECASE	Ignore case.
NORM_IGNOREKANATYPE	Do not differentiate between Hiragana and Katakana characters. Corresponding Hiragana and Katakana will compare as equal.
NORM_IGNORENONSPACE	Ignore nonspacing. This flag also removes Japanese accent characters.
NORM_IGNORESYMBOLS	Ignore symbols.
NORM_IGNOREWIDTH	Do not differentiate between a single-byte character and the same character as a double-byte character.
SORT_STRINGSORT	Treat punctuation the same as symbols.
If the LCMAP_SORTKEY flag is not specified, the LCMapString function performs string mapping. In this case the following restrictions apply:

•	LCMAP_LOWERCASE and LCMAP_UPPERCASE are mutually exclusive.

•	LCMAP_HIRAGANA and LCMAP_KATAKANA are mutually exclusive.

•	LCMAP_HALFWIDTH and LCMAP_FULLWIDTH are mutually exclusive.

•	SORT_STRINGSORT, NORM_IGNOREKANATYPE, NORM_IGNOREWIDTH, and NORM_IGNORECASE are not valid.

•	LCMAP_LOWERCASE and LCMAP_UPPERCASE are not valid in combination with any of the following flags: LCMAP_HIRAGANA, LCMAP_KATAKANA, LCMAP_HALFWIDTH, and LCMAP_FULLWIDTH.

When the LCMAP_SORTKEY flag is specified, the LCMapString function generates a sort key. In this case the following restriction applies:

•	All LCMAP_* options are invalid, with the sole exception of LCMAP_BYTEREV. In other words, LCMAP_SORTKEY is mutually exclusive with all other LCMAP_* flags, with the sole exception of LCMAP_BYTEREV. LCMAP_BYTEREV is valid for Windows NT only.

lpSrcStr

Pointer to a source string that the function maps or uses for sort key generation.

cchSrc

Specifies the number of bytes (ANSI version) or characters (Unicode version) in the string pointed to by the lpSrcStr parameter.

This count can include the NULL terminator, or not include it. If the NULL terminator is included in the character count, it does not greatly affect the mapping behavior. That is because NULL is considered to be unsortable, and always maps to itself.

A cchSrc value of −1 specifies that the string pointed to by lpSrcStr is null-terminated. If this is the case, and LCMapString is being used in its string-mapping mode, the function calculates the string's length itself, and null-terminates the mapped string stored into *lpDestStr.

lpDestStr

Pointer to a buffer into which the function stores the mapped string or sort key.

If LCMAP_SORTKEY is specified, LCMapString stores a sort key into the buffer. The sort key is stored as an array of byte values in the following format:

[all Unicode sort weights] 0x01 [all Diacritic weights] 0x01 [all Case weights] 0x01 [all Special weights] 0x00

Note that the sort key is null-terminated. This is true regardless of the value of cchSrc. Also note that, even if some of the sort weights are absent from the sort key, due to the presence of one or more ignore flags in dwMapFlags, the 0x01 separators and the 0x00 terminator are still present.

cchDest

Specifies the size in bytes (ANSI version) or characters (Unicode version) of the buffer pointed to by lpDestStr.

If the function is being used for string mapping, the size is a character count. If space for a NULL terminator is included in cchSrc, then cchDest must also include space for a NULL terminator.

If the function is being used to generate a sort key, the size is a byte count. This byte count must include space for the sort key 0x00 terminator.

If cchDest is zero, the function's return value is the number of characters, or bytes if LCMAP_SORTKEY is specified, required to hold the mapped string or sort key. In this case, the buffer pointed to by lpDestStr is not used.

Return Value

If the function succeeds, and the value of cchDest is nonzero, the return value is the number of characters, or bytes if LCMAP_SORTKEY is specified, written to the buffer. This count includes room for a NULL terminator.

If the function succeeds, and the value of cchDest is zero, the return value is the size of the buffer in characters, or bytes if LCMAP_SORTKEY is specified, required to receive the translated string or sort key. This size includes room for a NULL terminator.

If the function fails, the return value is 0. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER

Remarks

The mapped string is null terminated if the source string is null terminated.

The A version of this function maps strings to and from Unicode based on the specified LCID's default ANSI code page.

If the LCMAP_HIRAGANA flag is specified to map Katakana characters to Hiragana characters, and LCMAP_FULLWIDTH is not specified, the function only maps full-width characters to Hiragana. In this case, any half-width Katakana characters are placed as-is in the output string, with no mapping to Hiragana. An application must specify LCMAP_FULLWIDTH if it wants half-width Katakana characters mapped to Hiragana.

The lpSrcStr and lpDestStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

Even if the wide-character Unicode version of this function is called, the output string is only in WCHAR or CHAR format if the string mapping mode of LCMapString is used. If the sort key generation mode is used, specified by LCMAP_SORTKEY, the output is an array of byte values. An application can compare sort keys by using a byte-by-byte comparison.

An application can call the function with the NORM_IGNORENONSPACE and NORM_IGNORESYMBOLS flags set, and all other options flags cleared, in order to simply strip characters from the input string. If this is done with an input string that is not null-terminated, it is possible for LCMapString to return an empty string and not return an error.

The LCMapString function ignores the Arabic Kashida. If an application calls the function to create a sort key for a string containing an Arabic Kashida, there will be no sort key value for the Kashida.

The function treats the hyphen and apostrophe a bit differently than other punctuation symbols, so that words like coop and co-op stay together in a list. All punctuation symbols other than the hyphen and apostrophe sort before the alphanumeric characters. An application can change this behavior by setting the SORT_STRINGSORT flag. See CompareString for a more detailed discussion of this issue.

When LCMapString is used to generate a sort key, by setting the LC_MAPSORTKEY flag, the sort key stored into *lpDestStr may contain an odd number of bytes. The LCMAP_BYTEREV option (Windows NT only) only reverses an even number of bytes. If both options are chosen, the last (odd-positioned) byte in the sort key is not reversed. If the terminating 0x00 byte is an odd-positioned byte, then it remains the last byte in the sort key. If the terminating 0x00 byte is an even-positioned byte, it exchanges positions with the byte that precedes it.

See Also

CompareString, FoldString, MAKELCID


LeaveCriticalSection

The LeaveCriticalSection function releases ownership of the specified critical section object.

VOID LeaveCriticalSection(

LPCRITICAL_SECTION  lpcsCriticalSection	// address of critical section object
);
Parameters

lpcsCriticalSection

Points to the critical section object.

Return Value

This function does not return a value.

Remarks

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


LimitEmsPages

The LimitEmsPages function is obsolete.

This function is provided only for compatibility with 16-bit versions of Windows. New Win32-based applications do not require this function.


LineDDA

The LineDDA function determines which pixels should be highlighted for a line defined by the specified starting and ending points.

BOOL LineDDA(

int  nXStart,	// x-coordinate of line's starting point
int  nYStart,	// y-coordinate of line's starting point
int  nXEnd,	// x-coordinate of line's ending point
int  nYEnd,	// y-coordinate of line's ending point
LINEDDAPROC  lpLineFunc,	// address of application-defined callback function
LPARAM  lpData	// address of application-defined data
);
Parameters

nXStart

Specifies the x-coordinate of the line's starting point.

nYStart

Specifies the y-coordinate of the line's starting point.

nXEnd

Specifies the x-coordinate of the line's ending point.

nYEnd

Specifies the y-coordinate of the line's ending point.

lpLineFunc

Specifies the address of an application-defined callback function. For more information, see the LineDDAProc callback function.

lpData

Points to the application-defined data.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The LineDDA function passes the coordinates for each point along the line, except for the line's ending point, to the application-defined callback function. In addition to passing the coordinates of a point, this function passes any existing application-defined data.

The coordinates passed to the callback function match pixels on a video display only if the default transformations and mapping modes are used.

See Also

LineDDAProc


LineDDAProc

A LineDDAProc function is an application-defined callback function that processes coordinates from the LineDDA function. A value of type LINEDDAPROC is a pointer to such a function.

VOID CALLBACK LineDDAProc(

int  X,	// x-coordinate of point being evaluated
int  Y,	// y-coordinate of point being evaluated
LPARAM  lpData	// address of application-defined data
);
Parameters

X

Specifies the x-coordinate of the current point.

Y

Specifies the y-coordinate of the current point.

lpData

Points to the application-defined data.

Remarks

LineDDAProc is a placeholder for an application-defined function name.

An application registers a LineDDAProc function by passing its address to the LineDDA function.

See Also

LineDDA


LineTo

The LineTo function draws a line from the current position up to, but not including, the specified point.

BOOL LineTo(

HDC  hdc,	// device context handle
int  nXEnd,	// x-coordinate of line's ending point
int  nYEnd	// y-coordinate of line's ending point
);
Parameters

hdc

Identifies a device context.

nXEnd

Specifies the x-coordinate of the line's ending point.

nYEnd

Specifies the y-coordinate of the line's ending point.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The coordinates of the line's ending point are specified in logical units.

The line is drawn by using the current pen and, if the pen is a geometric pen, the current brush.

If LineTo succeeds, the current position is set to the specified ending point.

See Also

MoveToEx, Polyline, PolylineTo


listen

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

int listen (

SOCKET s,
int backlog
);
Parameters

s

A descriptor identifying a bound, unconnected socket.

backlog

The maximum length to which the queue of pending connections may grow.

Remarks

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

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

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

Compatibility

The backlog parameter is currently limited (silently) to 5. As in 4.3BSD, illegal values (less than 1 or greater than 5) are replaced by the nearest legal value.

Return Value

If the function succeeds, listen returns zero.

If the function failes, a value of SOCKET_ERROR is returned. To get extended error information, call WSAGetLastError.

Error Codes

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

accept, bind, connect, socket, WSAStartup


LoadAccelerators

The LoadAccelerators function loads the specified accelerator table.

HACCEL LoadAccelerators(

HINSTANCE  hinst,	// handle of application instance
LPCTSTR  lpTableName	// address of table-name string
);
Parameters

hinst

Identifies an instance of the module whose executable file contains the accelerator table to load.

lpTableName

Points to a null-terminated string that names the accelerator table to load. Alternatively, this parameter can specify the resource identifier of an accelerator-table resource in the low-order word and zero in the high-order word. The MAKEINTRESOURCE macro can be used to create this value.

Return Value

If the function succeeds, the return value is the handle of the loaded accelerator table.

If the function fails, the return value is NULL.

Remarks

If the accelerator table has not yet been loaded, the function loads it from the specified executable file.

Accelerator tables loaded from resources are freed automatically when the application terminates.

See Also

CopyAcceleratorTable, CreateAcceleratorTable, DestroyAcceleratorTable, MAKEINTRESOURCE


LoadBitmap

The LoadBitmap function loads the specified bitmap resource from a module's executable file.

HBITMAP LoadBitmap(

HINSTANCE  hinst,	// handle of application instance
LPCTSTR  lpszBitmap	// address of bitmap resource name
);
Parameters

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.

Return Value

If the function succeeds, the return value is the handle of the specified bitmap.

If the function fails, the return value is NULL.

Remarks

If the bitmap pointed to by the 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 the Win32 API. 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

CreateBitmap, DeleteObject, LoadCursor, LoadIcon, MAKEINTRESOURCE


LoadCursor

The LoadCursor function loads the specified cursor resource from the executable (.EXE) file associated with an application instance.

HCURSOR LoadCursor(

HINSTANCE  hinst,	// handle of application instance
LPCTSTR  lpszCursor	// name string or cursor resource identifier
);
Parameters

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	Windows NT only: Empty icon
IDC_NO	Slashed circle
IDC_SIZE	Windows NT only: Four-pointed arrow
IDC_SIZEALL	Same as IDC_SIZE
IDC_SIZENESW	Double-pointed arrow pointing northeast and southwest
IDC_SIZENS	Double-pointed arrow pointing north and south
IDC_SIZENWSE	Double-pointed arrow pointing northwest and southeast
IDC_SIZEWE	Double-pointed arrow pointing west and east
IDC_UPARROW	Vertical arrow
IDC_WAIT	Hourglass
Return Value

If the function succeeds, the return value is the handle of the newly loaded cursor.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

LoadCursor only loads the cursor resource if it has not been loaded; otherwise, it retrieves the handle of the existing resource. This function returns a valid cursor handle only if the 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 most appropriate for the cursor for the current display device. The cursor resource can be a color or monochrome bitmap.

See Also

LoadImage, MAKEINTRESOURCE, SetCursor, SetCursorPos, ShowCursor


LoadCursorFromFile

The LoadCursorFromFile function creates a cursor based on data contained in a file. The file is specified by its name or by a system cursor identifier. The function returns a handle to the newly created cursor. Files containing cursor data may be in either cursor (.CUR) or animated cursor (.ANI) format.

HCURSOR LoadCursorFromFile (

LPWSTR  lpszFilename	// pointer to name of cursor file, or system cursor identifier
);
Parameters

lpszFilename

Indicates the source of the file data to be used to create the cursor. The data in the file must be in either .CUR or .ANI format.

If the high-order word of lpszFileName is nonzero, it is a pointer to a string that is a fully qualified name of a file containing cursor data.

If the high-order word of lpszFileName is zero, the low-order word is a system cursor identifier. The function then searches the [Cursors] entry in the WIN.INI file for the file associated with the name of that system cursor. Here is a list of system cursor names and identifiers:

System Cursor Names	System Cursor Identifiers
"Arrow"	OCR_NORMAL
"IBeam"	OCR_IBEAM
"Wait"	OCR_WAIT
"Crosshair"	OCR_CROSS
"UpArrow"	OCR_UP
"Size"	OCR_SIZE
"Icon"	OCR_ICON
"SizeNWSE"	OCR_SIZENWSE
"SizeNESW"	OCR_SIZENESW
"SizeWE"	OCR_SIZEWE
"SizeNS"	OCR_SIZENS
"SizeAll"	OCR_SIZEALL
"No"	OCR_NO
"AppStarting"	OCR_APPSTARTING
For example, if the WIN.INI file contains the following :

[Cursors]

Arrow = "arrow.ani"

Then the call

LoadCursorFromFile((LPWSTR)OCR_NORMAL)

causes the LoadCursorFromFile function to obtain cursor data from the file ARROW.ANI. If the WIN.INI file doesn't contain an entry for the specified system cursor, the function fails and returns NULL.

Return Value

If the function is successful, the return value is a handle to the new cursor.

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

Value	Meaning
ERROR_FILE_NOT_FOUND	The specified file could not be found.
See Also

LoadCursor, SetCursor, SetSystemCursor


LoadIcon

The LoadIcon function loads the specified icon resource from the executable (.EXE) file associated with an application instance.

HICON LoadIcon(

HINSTANCE  hinst,	// handle of application instance
LPCTSTR  lpszIcon	// icon-name string or icon resource identifier
);
Parameters

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. Use the MAKEINTRESOURCE macro to create this value.

To use one of the Windows predefined icons, set the hinst parameter to NULL and the lpszIcon parameter to one of the following values:

Value	Description
IDI_APPLICATION	Default application icon.
IDI_ASTERISK	Asterisk (used in informative messages).
IDI_EXCLAMATION	Exclamation point (used in warning messages).
IDI_HAND	Hand-shaped icon (used in serious warning messages).
IDI_QUESTION	Question mark (used in prompting messages).
IDI_WINLOGO	Windows 95 only: Windows logo.
Return Value

If the function succeeds, the return value is the handle of the newly loaded icon.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

LoadIcon loads the icon resource only if it has not been loaded; otherwise, it retrieves a handle to the existing resource. The function searches the icon resource for the icon most appropriate for the current display. The icon resource can be a color or monochrome bitmap.

Windows 95 only: Use LoadImage instead of LoadIcon to load a nonstandard-sized icon (that is, a size other than 32 by 32 pixels).

See Also

CreateIcon, LoadImage, MAKEINTRESOURCE


LoadImage  (preliminaryWindows 95)
LoadImage  (preliminary−Windows 95)

The LoadImage function loads an icon, cursor, or bitmap.

HANDLE LoadImage(

HINSTANCE  hinst,	// handle of the instance that contains the image
LPCTSTR  lpszName,	// name or identifier of image
UINT  uType,	// type of image
int  cxDesired,	// desired width
int  cyDesired,	// desired height
UINT  fuLoad	// load flags
);
Parameters

hinst

Identifies an instance of the module that contains the image to be loaded. To load an OEM image, set this parameter to zero.

lpszName

Points to a null-terminated string that contains the name of the image to load.

If the fuLoad parameter includes the LR_LOADFROMFILE value, the lpszName parameter must be the name of the file that contains the image.

If the hinst parameter is zero, the low-order word of this parameter must be the identifier of the OEM image to load. The OEM image identifiers are defined in WINUSER.H and have the following prefixes:

Prefix	Meaning
OBM_	OEM bitmaps
OIC_	OEM icons
OCR_	OEM cursors
uType

Specifies the type of image to be loaded. This parameter can be one of the following values:

Value	Meaning
IMAGE_BITMAP	Loads a bitmap.
IMAGE_CURSOR	Loads a cursor.
IMAGE_ICON	Loads an icon.
cxDesired

Specifies the desired width, in pixels, of the icon or cursor. If this parameter is zero and fuLoad does not include LR_LOADREALSIZE, the function uses the SM_CXICON or SM_CXCURSOR system metric value to set the width.

cyDesired

Specifies the desired height, in pixels, of the icon or cursor. If this parameter is zero and fuLoad does not include LR_LOADREALSIZE, the function uses the SM_CYICON or SM_CYCURSOR system metric value to set the height.

fuLoad

Specifies a combination of the following values:

Value	Meaning
LR_DEFAULTCOLOR	Uses the color format of the display.
LR_LOADDEFAULTSIZE	Uses the width or height specified by the system metric values for cursors and icons, if the cxDesired or cyDesired values are set to zero. If this flag is not specified and cxDesired and cyDesired are set to zero, the function sets the size to that specified in the resource. If the resource contains multiple images, the function sets the size to that of the first image.
LR_LOADFROMFILE	Loads the image from the file specified by the lpszName parameter.
LR_LOADMAP3DCOLORS	Searches the color table for the image and replaces the following shades of gray with the corresponding 3D color:
Color	Replaced with
Dk Gray, RGB(128,128,128)	COLOR_3DSHADOW
Gray, RGB(192,192,192)	COLOR_3DFACE
Lt Gray, RGB(223,223,223)	COLOR_3DLIGHT
LR_LOADTRANSPARENT	Retrieves the color value of the first pixel in the image and replaces the corresponding entry in the color table with the default window color (COLOR_WINDOW). All pixels in the image that use that entry become the default window color. This value applies only to images that have corresponding color tables.  If fuLoad includes both the LR_LOADTRANSPARENT and LR_LOADMAP3DCOLORS values, LRLOADTRANSPARENT takes precedence. However, the color table entry is replaced with COLOR_3DFACE rather than COLOR_WINDOW.
LR_MONOCHROME	Loads the image in black and white.
LR_SHARED	Shares the image handle if the image is loaded multiple times. Do not use this value for images that have nontraditional sizes, that may change after loading, or that are loaded from a file.
Return Value

If the function succeeds, the return value is the handle of the newly loaded image.

If the function fails, the return value is NULL.

Windows NT: Even though LoadImage is supported only under Windows 95, it will not return ERROR_NOT_IMPLEMENTED under Windows NT.

See Also

CopyImage, LoadBitmap, LoadCursor, LoadIcon


LoadImageColorMatcher  (preliminaryWindows 95)
LoadImageColorMatcher  (preliminary−Windows 95)

The LoadImageColorMatcher function loads an installable image color matcher.

HANDLE LoadImageColorMatcher(

LPTSTR  lpszImageColorMatcher
);
Parameters

lpszImageColorMatcher

Pointer to a null-terminated string that names the image color matcher to load.

Return Value

If the function succeeds, the return value is the handle to the image color matcher.

If the function fails, the return value is one of the error values defined by the LoadLibrary function.

Remarks

LoadImageColorMatcher loads the image color matcher, setting the reference count to one, only if the matcher is not already loaded. In all other cases, the function merely increments the reference count by one. If a full path is not specified, the function uses the same path-searching techniques as the LoadLibrary function to locate the image color matcher file.

The handle is intended to be used with the FreeImageColorMatcher function to free the image color matcher when it is no longer needed.

See Also

FreeImageColorMatcher, LoadLibrary


LoadKeyboardLayout

The implementations of LoadKeyboardLayout in Windows 95 and Windows NT are substantially different. To accommodate these differences, this reference page first presents the Windows 95 implementation in its entirety, followed by the Windows NT version.

Windows 95:

The LoadKeyboardLayout function loads a new keyboard layout into the system. Several keyboard layouts can be loaded at a time, but only one at a time is active. Loading multiple keyboard layouts makes it possible to rapidly switch between layouts.

HKL LoadKeyboardLayout(

LPCTSTR  lpszKLName,	// name of layout to load
UINT  fuFlags	// keyboard layout flags
);
Parameters

lpszKLName

Points to the buffer that specifies the name of the keyboard layout. This name is a string composed from the hexadecimal value of the primary language identifier (low word) and a device identifier (high word). For example, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is named "00000409". Variants of U.S. English layout, such as the Dvorak layout, are named "00010409", "00020409", and so on. For a list of the primary language identifiers and secondary language identifiers that make up a language identifier, see the MAKELANGID macro.

fuFlags

Specifies how the keyboard layout is to be loaded. This parameter can be one of the following values:

Value	Meaning
KLF_ACTIVATE	If the given layout is not already loaded, the function loads and activates the layout for the current thread, inserting the layout at the head of the keyboard layouts list in front of the previously active layout. If the layout is already loaded and the KLF_REORDER value is not given, the function simply rotates the keyboard layouts list, making the next layout the active layout.
KLF_NOTELLSHELL	Prevents a ShellProc hook procedure from receiving an HSHELL_LANGUAGE hook code when the new layout is loaded. This value is typically used when an application loads multiple layouts, one after another. Applying this value to all but the last layout delays the shell's processing until all layouts have been added.
KLF_REORDER	Moves the given layout to the head of the keyboard layouts list, making that layout the active layout for the current thread. This value reorders the keyboard layouts list even if KLF_ACTIVATE is not given.
KLF_REPLACELANG	If the new layout has the same language identifier as a current layout, the new layout replaces the current one as the layout for that language. If this value is not given and the layouts have the same language identifiers, the current layout is not replaced and the function returns NULL.
KLF_SUBSTITUTE_OK	Substitues the given keyboard layout with another layout preferred by the user. The substitution occurs only if the registry key HKEY_CURRENT_USER\Keyboard Layout\Substitutes explicitly defines a substitution layout. For example, if the key includes the value name "00000409" with value "00010409", loading the U.S. English layout ("00000409") causes the Dvorak U.S. English layout ("00010409") to be loaded instead. The system uses KLF_SUBSTITUTE_OK when booting and it is recommended that all applications use this value too.
Return Value

If the function succeeds, the return value is the keyboard layout handle of the layout matched with the requested name or NULL if no matching keyboard is available.

Remarks

If a layout is to be loaded with the same language as a previously loaded one and the KLF_REPLACELANG flag is not set, the call fails. Only one loaded layout may be associated with a given language. (It is acceptable for multiple IMEs to be loaded with associations to the same language.)

An application can and will typically want to load the default layout or IME for a language and can do so by specifying only a string version of the language identifier. If an application wants to load a specific layout or IME, it should read the registry to determine the specific layout identifier to pass to LoadKeyboardLayout. In this case, a request to activate the default keyboard layout handle for a locale will activate the first matching one. A specific IME should be activated using an explicit keyboard layout handle returned from one of GetKeyboardLayout, GetKeyboardLayoutList or LoadKeyboardLayout.

See Also

ActivateKeyboardLayout, GetKeyboardLayout, GetKeyboardLayoutName, MAKELANGID, UnloadKeyboardLayout

Windows NT:

The LoadKeyboardLayout function loads a keyboard layout.

HKL LoadKeyboardLayout(

LPCTSTR  lpszKLName,	// address of buffer for layout name
UINT  fuFlags	// keyboard layout flags
);
Parameters

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, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is named "00000409". Variants of U.S. English layout, such as the Dvorak layout, are named "00010409",  "00020409", and so on. For a list of the primary language identifiers and sub-language identifiers that make up a language identifier, see the MAKELANGID macro.

fuFlags

Specifies how the keyboard layout is to be loaded. This parameter can be one of the following values:

Value	Meaning
KLF_ACTIVATE	The function loads the layout if it is not already loaded, and activates it.
KLF_REORDER	This flag is only meaningful if the KLF_ACTIVATE flag is set and the layout is already loaded. If these conditions are met and the KLF_REORDER bit is set, the function removes the specified layout from its position in the system's circular list of loaded layouts, and places it at the head of the list as the active layout.
	If the KLF_ACTIVATE bit is set and the layout is loaded but the KLF_REORDER bit is not set, the function simply rotates the system's circular list of loaded layouts.
	If the KLF_ACTIVATE flag is set and the layout is not already loaded, it is loaded as the active layout and inserted in the system's circular list of keyboard layouts ahead of the previously active layout.
KLF_SUBSTITUTE_OK	The specified layout is looked up in the user's profile (in the registry under the key HKEY_CURRENT_USER\Keyboard Layout\Substitutes) to find a substitution layout preferred by the user. For example, if there was a value in this section of name "00000409" equal to "00010409", loading the U.S. English layout ("00000409") with the KLF_SUBSTITUTE_OK flag set would cause the Dvorak U.S. English layout ("00010409") to be loaded.
KLF_UNLOADPREVIOUS	If KLF_ACTIVATE is specified, and the layout is loaded and activated successfully, the function unloads the previously active layout. Otherwise, the function ignores this flag.
Return Value

If the function succeeds, the return value is the handle of the keyboard layout.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Several keyboard layouts can be loaded at a time, but only one at a time is active. Loading multiple keyboard layouts makes it possible to switch rapidly between layouts.

See Also

ActivateKeyboardLayout, GetKeyboardLayoutName, UnloadKeyboardLayout


LoadLibrary

The LoadLibrary function maps the specified executable module into the address space of the calling process.

HINSTANCE LoadLibrary(

LPCTSTR  lpszLibFile	// address of filename of executable module
);
Parameters

lpszLibFile

Points to a null-terminated string that names the Win32 module (either a .DLL or .EXE file). The name specified is the filename of the module and is not related to the name stored in the library module itself, as specified by the LIBRARY keyword in the module-definition (.DEF) file.

If the string specifies a path but the file does not exist in the specified directory, the function fails.

If a path is not specified and the filename extension is omitted, the default library extension .DLL is appended. However, the filename string can include a trailing point character (.) to indicate that the module name has no extension. When no path is specified, the function searches for the file in the following sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT only: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

The first directory searched is the one directory containing the image file used to create the calling process (for more information, see the CreateProcess function). Doing this allows private dynamic-link library (DLL) files associated with a process to be found without adding the process's installed directory to the PATH environment variable.

Once the function obtains a fully qualified path to a library module file, the path is compared (case independently) to the full paths of library modules currently loaded into the calling process. These libraries include those loaded when the process was starting up as well as those previously loaded by LoadLibrary but not unloaded by FreeLibrary. If the path matches the path of an already loaded module, the function just increments the reference count for the module and returns the module handle for that library.

Return Value

If the function succeeds, the return value is a handle to the module.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

LoadLibrary can be used to map a DLL module and return a handle that can be used in GetProcAddress to get the address of a DLL function. LoadLibrary can also be used to map other executable modules. For example, the function can specify an .EXE file to get a handle that can be used in FindResource or LoadResource.

Module handles are not global or inheritable. A call to LoadLibrary by one process does not produce a handle that another process can use — for example, in calling GetProcAddress. The other process must make its own call to LoadLibrary for the module before calling GetProcAddress.

If the module is a DLL not already mapped for the calling process, the system calls the DLL's DllEntryPoint function with the DLL_PROCESS_ATTACH value. If the DLL's entry-point function does not return TRUE, LoadLibrary fails and returns NULL.

See Also

DllEntryPoint, FindResource, FreeLibrary, GetProcAddress, GetSystemDirectory, GetWindowsDirectory, LoadResource


LoadLibraryEx

The LoadLibraryEx function maps a specified executable module into the address space of the calling process. The executable module can be a .DLL or an .EXE file. The specified module may cause other modules to be mapped into the address space.

HINSTANCE LoadLibraryEx(

LPCTSTR  lpLibFileName,	// points to name of executable module
HANDLE  hFile,	// reserved, must be NULL
DWORD  dwFlags	// entry-point execution flag
);
Parameters

lpLibFileName

Points to a null-terminated string that names a Win32 executable module (either a .DLL or an .EXE file). The name specified is the filename of the executable module. This name is not related to the name stored in a library module itself, as specified by the LIBRARY keyword in the module-definition (.DEF) file.

If the string specifies a path, but the file does not exist in the specified directory, the function fails.

If the string does not specify a path, and the filename extension is omitted, the function appends the default library extension .DLL to the filename. However, the filename string can include a trailing point character (.) to indicate that the module name has no extension.

If the string does not specify a path, the function uses a standard search strategy to find the file. See the Remarks section following for a discussion of this.

If mapping the specified module into the address space causes the operating system to map in other, associated executable modules, the function can use either the standard search strategy or an alternate search strategy to find those modules. See the Remarks section following for a discussion of this.

Once the function obtains a fully qualified path to a library module file, the path is compared (in a case-independent manner) to the full paths of library modules that are currently loaded into the calling process. That set of libraries includes those that were loaded when the process was starting up, as well as those previously loaded by calls to LoadLibrary or LoadLibraryEx but not yet unloaded by calls to FreeLibrary. If the path matches the path of an already loaded module, the function just increments the reference count for the module, and returns the module handle for that library.

hFile

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

dwFlags

Specifies the action to take when loading the module. This parameter can be one of the following values:

Flag	Meaning
DONT_RESOLVE_DLL_REFERENCES
	Windows NT only:  If this value is given, and the executable module is a dynamic-link library (DLL), the operating system does not call the DllEntryPoint function for process and thread initialization and termination. Also, the system does not load additional executable modules that are referenced by the specified module. If this value is not given, and the executable module is a DLL, the operating system calls the DllEntryPoint function for process and thread initialization and termination. The system loads additional executable modules that are referenced by the specified module. The behavior of the function is then identical to that of LoadLibrary in this regard.
LOAD_LIBRARY_AS_DATAFILE
	If this value is given, the function does a simple mapping of the file into the address space. Nothing is done relative to executing or preparing to execute the code in the mapped file. The function loads the module as if it were a data file. You can use the module handle that the function returns in this case with the Win32 functions that operate on resources. Use this flag when you want to load a DLL in order to extract messages or resources from it, and have no intention of executing its code. If this value is not given, the function maps the file into the address space in the manner that is normal for an executable module. The behavior of the function is then identical to that of LoadLibrary in this regard.
LOAD_WITH_ALTERED_SEARCH_PATH
	If this value is given, and lpLibFileName specifies a path, the function uses the alternate file search strategy discussed in the Remarks section following to find associated executable modules that the specified module causes to be loaded. If this value is not given, or if lpLibFileName does not specify a path, the function uses the standard search strategy discussed in the Remarks section following to find associated executable modules that the specified module causes to be loaded. The behavior of the function is then identical to that of LoadLibrary in this regard.
Return Value

If the function succeeds, the return value is a handle to the mapped executable module.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Note that the DONT_RESOLVE_DLL_REFERENCES flag is only implemented on the Windows NT platform. It is not implemented on the Windows 95 platform.

The calling process can use the handle returned by this function to identify the module in calls to the GetProcAddress, FindResource, and LoadResource functions.

The LoadLibraryEx function is very similar to the LoadLibrary function. The differences consist of a set of optional behaviors that LoadLibraryEx provides. First, LoadLibraryEx can map a DLL module without calling the DllEntryPoint function of the DLL. Second, LoadLibraryEx can use either of two file search strategies to find executable modules that are associated with the specified module. Third, LoadLibraryEx can load a module in a way that is optimized for the case where the module will never be executed, loading the module as if it were a data file. You select these optional behaviors by setting the dwFlags parameter; if dwFlags is zero, LoadLibraryEx behaves identically to LoadLibrary.

If no path is specified, the LoadLibraryEx function uses the same standard file search strategy that LoadLibrary, SearchPath, and OpenFile use to find the executable module and any associated executable modules that it causes to be loaded. This standard strategy searches for a file in the following sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT only: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

If a path is specified, and the dwFlags parameter is set to LOAD_WITH_ALTERED_SEARCH_PATH, the LoadLibraryEx function uses an alternate file search strategy to find any executable modules that the specified module causes to be loaded. This alternate strategy searches for a file in the following sequence:

1.	The directory specified by the lpLibFileName path. In other words, the directory that the specified executable module is in.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT only: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

Note that the standard file search strategy and the alternate search strategy differ in just one way: the standard strategy starts its search in the calling application's directory, and the alternate strategy starts its search in the directory of the executable module that LoadLibraryEx is loading.

If you specify the alternate search strategy, its behavior continues until all associated executable modules have been located. Once the system starts processing DLL initialization routines, the system reverts to the standard search strategy.

See Also

DllEntryPoint, FindResource, FreeLibrary, GetProcAddress, GetSystemDirectory, GetWindowsDirectory, LoadLibrary, LoadResource, OpenFile, SearchPath


LoadMenu

The LoadMenu function loads the specified menu resource from the executable (.EXE) file associated with an application instance.

HMENU LoadMenu(

HINSTANCE  hinst,	// handle of application instance
LPCTSTR  lpMenuName	// menu name string or menu-resource identifier
);
Parameters

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.

Return Value

If the function succeeds, the return value is the handle of the menu resource.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The DestroyMenu function is used, before an application closes, to destroy the menu and free memory that the loaded menu occupied.

See Also

LoadMenuIndirect, MAKEINTRESOURCE


LoadMenuIndirect

The LoadMenuIndirect function loads the specified menu template in memory.

HMENU LoadMenuIndirect(

CONST MENUTEMPLATE  *lpMenuTemplate	// address of menu template
);
Parameters

lpMenuTemplate

Windows NT: Points to a menu template.

Windows 95: Points to a menu template or an extended menu template.

 A menu template consists of a MENUITEMTEMPLATEHEADER structure followed by one or more contiguous MENUITEMTEMPLATE structures. In Windows 95, an extended menu template consists of a MENUEX_TEMPLATE_HEADER structure followed by one or more contiguous MENUEX_TEMPLATE_ITEM structures.

Return Value

If the function succeeds, the return value is the handle of the menu.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

For both the ANSI and the Unicode version of this function, the strings in the MENUITEMTEMPLATE structure must be Unicode strings.

See Also

LoadMenu, MENUITEMTEMPLATE, MENUITEMTEMPLATEHEADER


LoadModule

The LoadModule function loads and executes a Windows-based application or creates a new instance of an existing Windows-based application.

This function is provided for compatibility with earlier versions of Windows. For Win32-based applications, use the CreateProcess function.

DWORD LoadModule(

LPCSTR  lpszModule,	// address of filename to load
LPVOID  lpvParamBlock	// address of parameter block for new module
);
Parameters

lpszModule

Points to a null-terminated string that contains the filename of the application to run. If the lpszModule parameter does not contain a directory path, Windows searches for the executable file in this order:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT only: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

lpvParamBlock

Points to an application-defined LOADPARMS32 structure that defines the new application's parameter block.

Set all unused members to NULL, except for lpCmdLine, which must point to a null-terminated string if it is not used.

Return Value

If the function succeeds, the return value is greater than 31.

If the function fails, the return value is an error value, which may be one of the following:

Value	Meaning
0	The system is out of memory or resources.
ERROR_BAD_FORMAT	The .EXE file is invalid (non-Win32 .EXE or error in .EXE image).
ERROR_FILE_NOT_FOUND	The specified file was not found.
ERROR_PATH_NOT_FOUND	The specified path was not found.
Remarks

Win32-based applications should use the CreateProcess function. In the Win32 API, the implementation of the LoadModule function calls CreateProcess. The following section describes how each parameter for CreateProcess is formed:

CreateProcess parameter	Value
lpszImageName	LoadModule 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, STARTUPINFO, WinExec


LoadResource

The LoadResource function loads the specified resource into global memory.

HGLOBAL LoadResource(

HINSTANCE  hModule,	// resource-module handle
HRSRC  hResInfo	// resource handle
);
Parameters

hModule

Identifies the module whose executable file contains the resource. If hModule is NULL, Windows loads the resource from the module that was used to create the current process.

hResInfo

Identifies the resource to be loaded. This handle must be created by using the FindResource or FindResourceEx function.

Return Value

If the function succeeds, the return value is a handle to the global memory block containing the data associated with the resource.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

It is not necessary to free a resource loaded by using the LoadResource function.

See Also

FindResource, FindResourceEx, LoadLibrary, LoadModule, LockResource


LoadString

For further information see LoadString in the Win32 (part 2) help file.

The LoadString function loads a string resource from the executable file associated with a specified module, copies the string into a buffer, and appends a terminating null character.

int LoadString(

HINSTANCE  hInstance,	// handle of module containing string resource
UINT  uID,	// resource identifier
LPTSTR  lpBuffer,	// address of buffer for resource
int  nBufferMax	// size of buffer
);
Parameters

hInstance

Identifies an instance of the module whose executable file contains the string resource.

uID

Specifies the integer identifier of the string to be loaded.

lpBuffer

Points to the buffer to receive the string.

nBufferMax

Specifies the size of the buffer in bytes (ANSI version) or characters (Unicode version). The string is truncated and null terminated if it is longer than the number of characters specified.

Return Value

If the function succeeds, the return value is the number of bytes (ANSI version) or characters (Unicode version) copied into the buffer, not including the null-terminating character, or zero if the string resource does not exist. To get extended error information, call GetLastError.

See Also

FormatMessage, LoadAccelerators, LoadBitmap, LoadCursor, LoadIcon, LoadMenu, LoadMenuIndirect


LocalAlloc

The LocalAlloc function allocates the specified number of bytes from the heap. In the linear Win32 API environment, there is no difference between the local heap and the global heap.

HLOCAL LocalAlloc(

UINT  uFlags,	// allocation attributes
UINT  uBytes	// number of bytes to allocate
);
Parameters

uFlags

Specifies how to allocate memory. If zero is specified, the default is the LMEM_FIXED flag. Except for the incompatible combinations that are specifically noted, any combination of the following flags can be specified. To indicate whether the function allocates fixed or movable memory, specify one of the first six flags:

Flag	Meaning
LMEM_FIXED
	Allocates fixed memory. This flag cannot be combined with the LMEM_MOVEABLE or LMEM_DISCARDABLE flag. The return value is a pointer to the memory block. To access the memory, the calling process simply casts the return value to a pointer.
LMEM_MOVEABLE
	Allocates movable memory. This flag cannot be combined with the LMEM_FIXED flag. The return value is the handle of the memory object. The handle is a 32-bit quantity that is private to the calling process. To translate the handle into a pointer, use the LocalLock function.
LPTR
	Combines the LMEM_FIXED and LMEM_ZEROINIT flags.
LHND
	Combines the LMEM_MOVEABLE and LMEM_ZEROINIT flags.
NONZEROLHND
	Same as the LMEM_MOVEABLE flag.
NONZEROLPTR
	Same as the LMEM_FIXED flag.
LMEM_DISCARDABLE
	Allocates discardable memory. This flag cannot be combined with the LMEM_FIXED flag. Some Win32-based applications may ignore this flag.
LMEM_NOCOMPACT
	Does not compact or discard memory to satisfy the allocation request.
LMEM_NODISCARD
	Does not discard memory to satisfy the allocation request.
LMEM_ZEROINIT
	Initializes memory contents to zero.
uBytes

Specifies the number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies the LMEM_MOVEABLE flag, the function returns a handle to a memory object that is marked as discarded.

Return Value

If the function succeeds, the return value is the handle of the newly allocated memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If the heap does not contain sufficient free space to satisfy the request, LocalAlloc returns NULL.

The GlobalAlloc and LocalAlloc functions are limited to a combined total of 65,536 handles for GMEM_MOVEABLE and LMEM_MOVEABLE memory per process. This limitation does not apply to GMEM_FIXED or LMEM_FIXED memory.

If this function succeeds, it allocates at least the amount requested. If the amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual number of bytes allocated, use the LocalSize function.

See Also

GlobalAlloc, LocalFree, LocalLock, LocalReAlloc, LocalSize


LocalCompact

The LocalCompact function is not implemented in the Win32 API.


LocalDiscard

The LocalDiscard function discards the specified local memory object. The lock count of the memory object must be zero.

HLOCAL LocalDiscard(

HLOCAL  hlocMem	// handle of local memory object
);
Parameters

hlocMem

Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Value

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

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

LocalDiscard discards only local objects allocated by a process with the LMEM_DISCARDABLE flag. If a process attempts to discard a fixed or locked object, the function fails.

Although LocalDiscard discards the object's memory block, the handle of the object remains valid. A process can subsequently pass the handle to the LocalReAlloc function to allocate another local memory object identified by the same handle.

See Also

LocalAlloc, LocalReAlloc


LocalFileTimeToFileTime

The LocalFileTimeToFileTime function converts a local file time to a file time based on the Coordinated Universal Time (UTC).

BOOL LocalFileTimeToFileTime(

CONST FILETIME *  lpftLocal,	// address of local file time to convert
LPFILETIME  lpft	// address of converted file time
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE; otherwise, it is FALSE. To get extended error information, use the GetLastError function.

See Also

FILETIME, FileTimeToLocalFileTime


LocalFlags

The LocalFlags function returns information about the specified local memory object.

UINT LocalFlags(

HLOCAL  hlocMem	// handle of local memory object
);
Parameters

hlocMem

Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Value

If the function succeeds, the return value is a 32-bit value that specifies the allocation flags and the lock count for the memory object.

If the function fails, the return value is the LMEM_INVALID_HANDLE flag, indicating that the local handle is not valid. To get extended error information, call GetLastError.

Remarks

The low-order byte of the low-order word of the return value contains the lock count of the object. To retrieve the lock count from the return value, use the LMEM_LOCKCOUNT mask with the bitwise AND (&) operator. The lock count of memory objects allocated with the LMEM_FIXED flag is always zero.

The high-order byte of the low-order word of the return value indicates the allocation flags of the memory object. It can be zero or any combination of the following flags:

Value	Description
LMEM_DISCARDABLE	The object's memory block can be discarded.
LMEM_DISCARDED	The object's memory block has been discarded.
See Also

GlobalFlags, LocalAlloc, LocalDiscard, LocalLock, LocalReAlloc, LocalUnlock


LocalFree

The LocalFree function frees the specified local memory object and invalidates its handle.

HLOCAL LocalFree(

HLOCAL  hlocMem	// handle of local memory object
);
Parameters

hlocMem

Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Value

If the function succeeds, the return value is NULL.

If the function fails, the return value is equal to the handle of the local memory object. To get extended error information, call GetLastError.

Remarks

If the process tries to examine or modify the memory after it has been freed, heap corruption may occur or an access violation exception (EXCEPTION_ACCESS_VIOLATION) may be generated.

If the hlocMem parameter is NULL, LocalFree ignores the parameter and returns NULL.

LocalFree succeeds even if the memory object is locked by a previous call to the LocalLock function. The LocalLock function locks a local memory object and increments the lock count by one. The LocalUnlock function unlocks it and decrements the lock count by one. To get the lock count of a local memory object, use the LocalFlags function. LocalFree will free a locked memory object. A locked memory object has a lock count greater than zero.

Both GlobalFree and LocalFree will free a locked memory object. However, if you run an application under a debug version of Windows NT or Windows 95, both GlobalFree and LocalFree will issue a message that tells you that this is happening. If you are debugging the application, GlobalFree and LocalFree will enter a hard-coded breakpoint just before freeing a locked object. This lets you double-check the intended behavior.

See Also

GlobalFree, LocalAlloc, LocalFlags, LocalLock, LocalReAlloc, LocalUnlock


LocalHandle

The LocalHandle function retrieves the handle associated with the specified pointer to a local memory object.

HLOCAL LocalHandle(

LPCVOID  lpvMem	// address of local memory object
);
Parameters

lpvMem

Points to the first byte of the local memory object. This pointer is returned by the LocalLock function.

Return Value

If the function succeeds, the return value is the handle of the specified local memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

When the LocalAlloc function allocates a local memory object with the LMEM_MOVEABLE flag, it returns the handle of the object. The LocalLock function converts this handle into a pointer to the object's memory block, and LocalHandle converts the pointer back into a handle.

See Also

LocalAlloc, LocalLock


LocalInit

The LocalInit function has been deleted.


LocalLock

The LocalLock function locks a local memory object and returns a pointer to the first byte of the object's memory block. The memory block associated with a locked memory object cannot be moved or discarded. For memory objects allocated with the LMEM_MOVEABLE flag, the function increments the object's lock count.

LPVOID LocalLock(

HLOCAL  hlocMem	// handle of local memory object
);
Parameters

hlocMem

Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Value

If the function succeeds, the return value is a pointer to the first byte of the memory block.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, LocalLock increments the count by one, and the LocalUnlock function decrements the count by one. For each call that a process makes to LocalLock for an object, it must eventually call LocalUnlock. Locked memory will not be moved or discarded unless the memory object is reallocated by using the LocalReAlloc function. The memory block of a locked memory object remains locked in memory until its lock count is decremented to zero, at which time it can be moved or discarded.

Memory objects allocated with the LMEM_FIXED flag always have a lock count of zero. For these objects, the value of the returned pointer is equal to the value of the specified handle.

If the specified memory block has been discarded or if the memory block has a zero-byte size, this function returns NULL.

Discarded objects always have a lock count of zero.

See Also

LocalAlloc, LocalFlags, LocalReAlloc, LocalUnlock


LocalReAlloc

The LocalReAlloc function changes the size or the attributes of a specified local memory object. The size can increase or decrease.

HLOCAL LocalReAlloc(

HLOCAL  hMem,	// handle of local memory object
UINT  uBytes,	// new size of block
UINT  uFlags	// how to reallocate object
);
Parameters

hMem

Identifies the local memory object to be reallocated. This handle is returned by either the LocalAlloc or LocalReAlloc function.

uBytes

Specifies the new size, in bytes, of the memory block. If this parameter is zero and the uFlags parameter specifies the LMEM_MOVEABLE flag, the function returns a handle to a memory object that is marked as discarded. If uFlags specifies the LMEM_MODIFY flag, this parameter is ignored.

uFlags

Specifies how to reallocate the local memory object. If the LMEM_MODIFY flag is specified, this parameter modifies the attributes of the memory object, and the uBytes parameter is ignored. Otherwise, this parameter controls the reallocation of the memory object.

The LMEM_MODIFY flag can be combined with either or both of the following flags:

Flag	Meaning
LMEM_DISCARDABLE
	Allocates discardable memory if the LMEM_MODIFY flag is also specified. This flag is ignored, unless the object was previously allocated as movable or the LMEM_MOVEABLE flag is also specified.
LMEM_MOVEABLE
	You cannot combine LMEM_MOVEABLE with LMEM_MODIFY to change a fixed memory object into a movable one. The function returns an error if an application attempts this.
If uFlags does not specify LMEM_MODIFY, this parameter can be any combination of the following flags:

Flag	Meaning
LMEM_MOVEABLE
	If uBytes is zero, discards a previously movable and discardable memory block. If the object's lock count is not zero or the block is not movable and discardable, the function fails.
	If uBytes is nonzero, enables the system to move the reallocated block to a new location without changing the movable or fixed attribute of the memory object. If the object is fixed, the handle returned may be different from the handle specified in the hMem parameter. If the object is movable, the block can be moved without invalidating the handle, even if the object is currently locked by a previous call to the LocalLock function. To get the new address of the memory block, use LocalLock.
LMEM_NOCOMPACT
	Prevents memory from being compacted or discarded to satisfy the allocation request.
LMEM_ZEROINIT
	Causes the additional memory contents to be initialized to zero if the memory object is growing in size.
Return Value

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

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If LocalReAlloc reallocates a movable object, the return value is the handle of the memory object. To convert the handle to a pointer, use the LocalLock function.

If LocalReAlloc reallocates a fixed object, the value of the handle returned is the address of the first byte of the memory block. To access the memory, a process can simply cast the return value to a pointer.

See Also

LocalAlloc, LocalFree, LocalLock


LocalShrink

The LocalShrink function is obsolete. It has no meaning in the 32-bit envronment.


LocalSize

The LocalSize function returns the current size, in bytes, of the specified local memory object.

UINT LocalSize(

HLOCAL  hlocMem	// handle of local memory object
);
Parameters

hlocMem

Identifies the local memory object. This handle is returned by the LocalAlloc, LocalReAlloc, or LocalHandle function.

Return Value

If the function succeeds, the return value is the size, in bytes, of the specified local memory object. If the specified handle is not valid or if the object has been discarded, the return value is zero. To get extended error information, call GetLastError.

Remarks

The size of a memory block may be larger than the size requested when the memory was allocated.

To verify that the specified object's memory block has not been discarded, call the LocalFlags function before calling LocalSize.

See Also

LocalAlloc, LocalFlags, LocalHandle, LocalReAlloc


LocalUnlock

The LocalUnlock function decrements the lock count associated with a memory object that was allocated with the LMEM_MOVEABLE flag. This function has no effect on memory objects allocated with the LMEM_FIXED flag.

BOOL LocalUnlock(

HLOCAL  hlocMem	// handle of local memory object
);
Parameters

hlocMem

Identifies the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Value

If the memory object is still locked after decrementing the lock count, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. If GetLastError returns NO_ERROR, the memory object is unlocked.

Remarks

The internal data structures for each memory object include a lock count that is initially zero. For movable memory objects, the LocalLock function increments the count by one, and LocalUnlock decrements the count by one. For each call that a process makes to LocalLock for an object, it must eventually call LocalUnlock. Locked memory will not be moved or discarded unless the memory object is reallocated by using the LocalReAlloc function. The memory block of a locked memory object remains locked until its lock count is decremented to zero, at which time it can be moved or discarded.

If the memory object is already unlocked, LocalUnlock returns FALSE and GetLastError reports ERROR_NOT_LOCKED. Memory objects allocated with the LMEM_FIXED flag always have a lock count of zero and cause the ERROR_NOT_LOCKED error.

A process should not rely on the return value to determine the number of times it must subsequently call LocalUnlock for the memory block.

See Also

LocalAlloc, LocalFlags, LocalLock, LocalReAlloc


LockFile

The LockFile function locks a region in an open file. Locking a region prevents other processes from accessing the region.

BOOL LockFile(

HANDLE  hFile,	// handle of file to lock
DWORD  dwFileOffsetLow,	// low-order word of lock region offset
DWORD  dwFileOffsetHigh,	// high-order word of lock region offset
DWORD  cbLockLow,	// low-order word of length to lock
DWORD  cbLockHigh	// high-order word of length to lock
);
Parameters

hFile

Identifies the file with a region to be locked. The file handle must have been created with GENERIC_READ or GENERIC_WRITE access to the file (or both).

dwFileOffsetLow

Specifies the low-order word of the starting byte offset in the file where the lock should begin.

dwFileOffsetHigh

Specifies the high-order word of the starting byte offset in the file where the lock should begin.

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Locking a region of a file gives the locking process exclusive access to the specified region. File locks are not inherited by processes created by the locking process.

Locking a region of a file denies all other processes both read and write access to the specified region. Locking a region that goes beyond the current end-of-file position is not an error.

Locks may not overlap an existing locked region of the file.

The UnlockFile function unlocks a file region locked by LockFile.

See Also

CreateFile, UnlockFile


LockFileEx

The LockFileEx function locks a byte range within an open file for shared or exclusive access.

BOOL LockFileEx(

HANDLE  hFile,	// handle of file to lock
DWORD  dwFlags,	// functional behavior modification flags
DWORD  dwReserved,	// reserved, must be set to zero
DWORD  nNumberOfBytesToLockLow,	// low-order 32 bits of length to lock
DWORD  nNumberOfBytesToLockHigh,	// high-order 32 bits of length to lock
LPOVERLAPPED  lpOverlapped	// addr. of structure with lock region start offset
);
Parameters

hFile

Identifies an open handle to a file that is to have a range of bytes locked for shared or exclusive access. The handle must have been created with either GENERIC_READ or GENERIC_WRITE access to the file.

dwFlags

Specifies flags that modify the behavior of this function. This parameter may be one or more of the following values:

Value	Meaning
LOCKFILE_FAIL_IMMEDIATELY	If this value is specified, the function returns immediately if it is unable to acquire the requested lock. Otherwise, it waits.
LOCKFILE_EXCLUSIVE_LOCK	If this value is specified, the function requests an exclusive lock. Otherwise, it requests a shared lock.
dwReserved

Reserved parameter; must be set to zero.

nNumberOfBytesToLockLow

Specifies the low-order 32 bits of the length of the byte range to lock.

nNumberOfBytesToLockHigh

Specifies the high-order 32 bits of the length of the byte range to lock.

lpOverlapped

Points to an OVERLAPPED structure that the function uses with the locking request. This structure, which is required, contains the file offset of the beginning of the lock range.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Locking a region of a file is used to acquire shared or exclusive access to the specified region of the file. File locks are not inherited by a new process during process creation.

Locking a portion of a file for exclusive access denies all other processes both read and write access to the specified region of the file. Locking a region that goes beyond the current end-of-file position is not an error.

Locking a portion of a file for shared access denies all other processes write access to the specified region of the file, but allows other processes to read the locked region.

If an exclusive lock is requested for a file that is already locked either shared or exclusively by other threads, this call waits until the lock is granted, unless the LOCKFILE_FAIL_IMMEDIATELY flag is specified.

Locks may not overlap an existing locked region of the file.

See Also

CreateFile, LockFile, OVERLAPPED, UnlockFile, UnlockFileEx


LockResource

The LockResource function locks the specified resource in memory.

LPVOID LockResource(

HGLOBAL  hglb	// handle to resource to lock
);
Parameters

hglb

Identifies the resource to be locked. The LoadResource function returns this handle.

Return Value

If the loaded resource is locked, the return value is a pointer to the first byte of the resource; otherwise, it is NULL.

Remarks

It is not necessary for Win32-based applications to unlock resources that were locked by the LockResource function.

Trying to lock a resource by using the handle returned by the FindResource or FindResourceEx function will not work. You will get back a value that is incorrect and points to random data.

See Also

FindResource, FindResourceEx, LoadResource


LockSegment

The LockSegment function is obsolete. It has no meaning in the 32-bit envronment.


LockServiceDatabase

The LockServiceDatabase function locks a specified database.

SC_LOCK LockServiceDatabase(

SC_HANDLE  schSCManager	// handle of service control manager database
);
Parameters

schSCManager

Identifies the service control manager database. The OpenSCManager function returns this handle, which must have SC_MANAGER_LOCK access.

Return Value

If the function succeeds, the return value is a lock to the specified service control manager database.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Errors

The following error code may be set by the service control manager. Other error codes may be set by registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The specified handle was not opened with SC_MANAGER_LOCK access.
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_SERVICE_DATABASE_LOCKED	The database is locked.
Remarks

The LockServiceDatabase function tries to acquire a lock on the specified database. Only one process at a time can have a lock on a database.

A lock is a protocol used by setup and configuration programs and the service control manager to serialize access to the service tree in the registry. The only time the service control manager acquires a lock is when it is starting a service. Setup and configuration programs are expected to acquire a lock before using the ChangeServiceConfig or SetServiceObjectSecurity function to reconfigure a service. They should also acquire a lock before using the registry functions to reconfigure a service. The lock prevents the service control manager from starting a service while it is being reconfigured.

A call to the StartService function to start a service in a locked database fails. All other service control manager functions are not affected by a lock.

The lock is held until the SC_LOCK handle is specified in a subsequent call to the UnlockServiceDatabase function. If a process that is holding a lock terminates, the service control manager automatically cleans up and releases the lock.

See Also

ChangeServiceConfig, OpenSCManager, QueryServiceLockStatus, SetServiceObjectSecurity, StartService, UnlockServiceDatabase


LockWindowUpdate

The LockWindowUpdate function disables or reenables drawing in the specified window. Only one window can be locked at a time.

BOOL LockWindowUpdate(

HWND  hwndLock	// handle of window to lock
);
Parameters

hwndLock

Specifies the window in which drawing will be disabled. If this parameter is NULL, drawing in the locked window is enabled.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE, indicating that an error occurred or another window was already locked.

Remarks

If an application with a locked window (or any locked child windows) calls the GetDC, GetDCEx, or BeginPaint function, the called function returns a device context with a visible region that is empty. This will occur until the application unlocks the window by calling LockWindowUpdate, specifying a value of NULL for hwndLock.

If an application attempts to draw within a locked window, the system records the extent of the attempted operation in a bounding rectangle. When the window is unlocked, the system invalidates the area within this bounding rectangle, forcing an eventual WM_PAINT message to be sent to the previously locked window and its child windows. If no drawing has occurred while the window updates were locked, no area is invalidated.

LockWindowUpdate does not make the given window invisible and does not clear the WS_VISIBLE style bit.

A locked window cannot be moved.

See Also

BeginPaint, GetDC, GetDCEx, WM_PAINT


LogonUser  (preliminaryWindows NT)
LogonUser  (preliminary−Windows NT)

The LogonUser function attempts to perform a user logon operation. You specify the user with a user name and domain, and authenticate the user with a clear-text password. If the function succeeds, you receive a handle to a token that represents the logged-on user. You can then use this token handle to impersonate the specified user, or to create a process running in the context of the specified user.

BOOL LogonUser(

LPTSTR lpszUsername,	// string that specifies the user name
LPTSTR lpszDomain,	// string that specifies the domain or servero
LPTSTR lpszPassword,	// string that specifies the password
DWORD dwLogonType,	// specifies the type of logon operation
DWORD dwLogonProvider,	// specifies the logon provider
PHANDLE phToken	// pointer to variable to receive token handle
);
Parameters

lpszUsername

Pointer to a zero-terminated string that specifies the user name. This is the name of the user account to log on to.

lpszDomain

Pointer to a zero-terminated string that specifies the domain or server to log on to.

lpszPasswordc

Pointer to a zero-terminated string that specifies the clear-text password for the user account specified by lpszUsername.

dwLogonType

Specifies the type of logon operation to perform. The following logon types are defined:

Value	Meaning
LOGON32_LOGON_BATCH
LOGON32_LOGON_INTERACTIVE
LOGON32_LOGON_SERVICE
dwLogonProvider

Specifies the logon provider. The following logon providers are defined:

Value	Meaning
LOGON32_PROVIDER_DEFAULT	Use the standard logon provider. This is the recommended value for dwLogonProvider. It gives an application the maximum upward compatibility with future releases of Windows NT.
LOGON32_PROVIDER_WINNT35	Use the Windows NT release 3.5 logon provider.
phToken

Pointer to a HANDLE variable that receives a handle to a token that represents the specified user.

You can use this token handle in calls to the ImpersonateLoggedOnUser and CreateProcessAsUser functions.

When you no longer need this handle, close it by calling the CloseHandle function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The process that calls LogonUser must have the SeTcbPrivilege privilege. The privilege does not need to be enabled. The LogonUser function enables the privilege as necessary. The function fails if the calling process does not have the SeTcbPrivilege privilege, and GetLastError returns the error code ERROR_PRIVILEGE_NOT_HELD.

See Also

CreateProcessAsUser, ImpersonateLoggedOnUser


LookupAccountName

The LookupAccountName function accepts the name of a system and an account as input. It retrieves a security identifier (SID) for the account and the name of the domain on which the account was found.

BOOL LookupAccountName(

LPCTSTR  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
);
Parameters

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 a SID_NAME_USE enumerated type indicating the type of the account when the function returns.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The LookupAccountName function attempts to find a security identifier for the specified name by first checking a list of well-known SIDs. If the name does not correspond to a well-known SID, the function checks built-in and administratively defined local accounts. Next, the function checks the primary domain. If the name is not found there, trusted domains are checked.

See Also

EqualPrefixSid, GetUserName, LookupAccountSid


LookupAccountSid

The LookupAccountSid function accepts a security identifier (SID) as input. It retrieves the name of the account for this SID and the name of the first domain on which this SID is found.

BOOL LookupAccountSid(

LPCTSTR  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
);
Parameters

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 Server systems, the domain name returned for most accounts in the local computer's security database is the name of the domain for which the Windows NT Server is a domain controller.

Some accounts are predefined by the system. The domain name returned for these accounts is BUILTIN.

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The LookupAccountSid function attempts to find a name for the specified security identifier by first checking a list of well-known SIDs. If the supplied SID does not correspond to a well-known SID, the function checks built-in and administratively defined local accounts. Next, the function checks the primary domain. Security identifiers not recognized by the primary domain are checked against the trusted domains corresponding to their SID prefixes.

See Also

EqualPrefixSid, LookupAccountName


LookupIconIdFromDirectory

The LookupIconIdFromDirectory function searches through icon or cursor data for the icon or cursor that best fits the current display device.

int LookupIconIdFromDirectory(

PBYTE  presbits,	// address of resource data
BOOL  fIcon	// look for icon or cursor
);
Parameters

presbits

Points to the icon or cursor directory data. Because this function does not validate the resource data, it causes a general protection (GP) fault or returns an undefined value if presbits is not pointing to valid resource data.

fIcon

Specifies whether an icon or a cursor is sought. If this parameter is TRUE, the function is searching for an icon; if the parameter is FALSE, the function is searching for a cursor.

Return Value

If the function succeeds, the return value is an integer resource identifier for the icon or cursor that best fits the current display device.

Remarks

A resource file of type RT_GROUP_ICON (RT_GROUP_CURSOR indicates cursors) contains icon (or cursor) data in several device-dependent and device-independent formats. LookupIconIdFromDirectory searches the resource file for the icon (or cursor) that best fits the current display device and returns its integer identifier. The FindResource and FindResourceEx functions use the MAKEINTRESOURCE macro with this identifier to locate the resource in the module.

The icon directory is loaded from a resource file with resource type RT_GROUP_ICON (or RT_GROUP_CURSOR for cursors), and an integer resource name for the specific icon to be loaded. LookupIconIdFromDirectory returns an integer identifier that is the resource name of the icon that best fits the current display device.

The LoadIcon, LoadCursor, and LoadImage (in Windows 95) functions use this function to search the specified resource data for the icon or cursor that best fits the current display device.

See Also

CreateIconFromResource, CreateIconIndirect, FindResource, FindResourceEx, GetIconInfo, LoadCursor, LoadIcon, LoadImage, MAKEINTRESOURCE


LookupIconIdFromDirectoryEx  (preliminaryWindows 95)
LookupIconIdFromDirectoryE  [image] x  (preliminary−Windows 95)

The LookupIconIdFromDirectory function searches through icon or cursor data for the icon or cursor that best fits the current display device.

int LookupIconIdFromDirectoryEx(

PBYTE  presbits,	// address of resource data
BOOL  fIcon,	// icon or cursor flag
int  cxDesired,	// desired width of icon or cursor
int  cyDesired,	// desired height of icon or cursor
UINT  uFlags	// resource flags
);
Parameters

presbits

Points to the icon or cursor directory data. Because this function does not validate the resource data, it causes a general protection (GP) fault or returns an undefined value if presbits is not pointing to valid resource data.

fIcon

Specifies whether an icon or a cursor is sought. If this parameter is TRUE, the function is searching for an icon; if the parameter is FALSE, the function is searching for a cursor.

cxDesired

Specifies the desired width, in pixels, of the icon. If this parameter is zero and uFlags does not include LR_LOADREALSIZE, the function uses the SM_CXICON or SM_CXCURSOR system metric value.

cyDesired

Specifies the desired height, in pixels, of the icon. If this parameter is zero and uFlags does not include LR_LOADREALSIZE, the function uses the SM_CYICON or SM_CYCURSOR system metric value.

uFlags

Specifies a combination of the following values:

Value	Meaning
LR_DEFAULTCOLOR	Uses the default color format.
LR_LOADREALSIZE	Sets the width and height as specified by the biWidth and biHeight members of the BITMAPINFOHEADER structure that defines the icon or cursor. The cxDesired and cyDesired parameters are ignored.
LR_MONOCHROME	Creates a monochrome icon or cursor.
Return Value

If the function succeeds, the return value is an integer resource identifier for the icon or cursor that best fits the current display device.

Remarks

A resource file of type RT_GROUP_ICON (RT_GROUP_CURSOR indicates cursors) contains icon (or cursor) data in several device-dependent and device-independent formats. LookupIconIdFromDirectory searches the resource file for the icon (or cursor) that best fits the current display device and returns its integer identifier. The FindResource and FindResourceEx functions use the MAKEINTRESOURCE macro with this identifier to locate the resource in the module.

The icon directory is loaded from a resource file with resource type RT_GROUP_ICON (or RT_GROUP_CURSOR for cursors), and an integer resource name for the specific icon to be loaded. LookupIconIdFromDirectory returns an integer identifier that is the resource name of the icon that best fits the current display device.

The LoadIcon, LoadImage, and LoadCursor functions use this function to search the specified resource data for the icon or cursor that best fits the current display device.

See Also

CreateIconFromResourceEx, CreateIconIndirect, FindResource, FindResourceEx, GetIconInfo, LoadCursor, LoadIcon, LoadImage, MAKEINTRESOURCE


LookupPrivilegeDisplayName

The LookupPrivilegeDisplayName function retrieves a displayable name representing a specified privilege.

BOOL LookupPrivilegeDisplayName(

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
);
Parameters

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

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

For 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

The LookupPrivilegeName function retrieves the name corresponding to the privilege represented on a specific system by a specified locally unique identifier (LUID).

BOOL LookupPrivilegeName(

LPCTSTR  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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

For this release of Windows NT, only the privileges specified in the Defined Privileges section of WINNT.H are supported by this function.

See Also

LookupPrivilegeDisplayName, LookupPrivilegeValue


LookupPrivilegeValue

The LookupPrivilegeValue function retrieves the locally unique identifier (LUID) used on a specified system to locally represent the specified privilege name.

BOOL LookupPrivilegeValue(

LPCTSTR  lpszSystemName,	// address of string specifying the system
LPCTSTR  lpszPrivilege,	// address of string specifying the privilege
PLUID  pluid	// address of locally unique identifier
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

For 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


LPtoDP

The LPtoDP function converts logical coordinates into device coordinates. The conversion depends on the mapping mode of the device context, the settings of the origins and extents for the window and viewport, and the world transformation.

BOOL LPtoDP(

HDC  hdc,	// handle of device context
LPPOINT  lpPoints,	// array of points
int  nCount	// count of points
);
Parameters

hdc

Identifies the DC.

lpPoints

Points to an array of POINT structures. The x-coordinates and y-coordinates contained in each of the POINT structures will be transformed.

nCount

Specifies the number of points in the array.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

This function fails if the logical coordinates exceed 32 bits, or if the converted device coordinates exceed 27 bits. In the case of such an overflow, the results for all the points are undefined.

See Also

DPtoLP, POINT


lstrcat

The lstrcat function appends one string to another.

LPTSTR lstrcat(

LPTSTR  lpszString1,	// address of buffer for concatenated strings
LPCTSTR  lpszString2	// address of string to add to string1
);
Parameters

lpszString1

Points to a null-terminated string. The buffer 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.

Return Value

If the function succeeds, the return value is a pointer to the buffer.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

lstrcmp, lstrcmpi, lstrcpy, lstrlen


lstrcmp

For further information see lstrcmp in the Win32 (part 2) help file.

The lstrcmp function compares two character strings. The comparison is case sensitive.

int lstrcmp(

LPCTSTR  lpszString1,	// address of first string
LPCTSTR  lpszString2	// address of second string
);
Parameters

lpszString1

Points to the first null-terminated string to be compared.

lpszString2

Points to the second null-terminated string to be compared.

Return Value

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.

Remarks

The lstrcmp function compares two strings by checking the first characters against each other, the second characters against each other, and so on until it finds an inequality or reaches the ends of the strings.

The function returns the difference of the values of the first unequal characters it encounters. For example, lstrcmp determines that "abcz" is greater than "abcdefg" and returns the difference of z and d.

The language (locale) selected by the user at setup time, or via the control panel, determines which string is greater (or whether the strings are the same). If no language (locale) is selected, Windows performs the comparison by using default values. In the Windows United States language functions, uppercase characters have lower values than lowercase characters.

With a double-byte character set (DBCS) version of Windows, this function can compare two DBCS strings.

The Win32 lstrcmp function uses a word sort, rather than a string sort. A word sort treats hyphens and apostrophes differently than it treats other symbols that are not alphanumeric, in order to ensure that words such as "coop" and "co-op" stay together within a sorted list. Note that in 16-bit versions of Windows, lstrcmp  uses a string sort. For a detailed discussion of word sorts and string sorts, see the Remarks section of the reference page for the CompareString function .

See Also

CompareString, lstrcat, lstrcmpi, lstrcpy, lstrlen


lstrcmpi

For further information see lstrcmpi in the Win32 (part 2) help file.

The lstrcmpi function compares two character strings. The comparison is not case sensitive.

int lstrcmpi(

LPCTSTR  lpszString1,	// address of first string
LPCTSTR  lpszString2	// address of second string
);
Parameters

lpszString1

Points to the first null-terminated string to be compared.

lpszString2

Points to the second null-terminated string to be compared.

Return Value

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.

Remarks

The lstrcmpi function compares two strings by checking the first characters against each other, the second characters against each other, and so on until it finds an inequality or reaches the ends of the strings.

The function returns the difference of the values of the first unequal characters it encounters. For example, lstrcmpi determines that "abcz" is greater than "abcdefg" and returns the difference of z and d.

The language (locale) selected by the user at setup time, or by using the control panel, determines which string is greater (or whether the strings are the same). If no language (locale) is selected, Windows performs the comparison by using default values.

For some locales, the lstrcmpi function may be insufficient. If this occurs, use CompareString to ensure proper comparison. For example, in Japan call CompareString with the IGNORE_CASE, IGNORE_KANATYPE, and IGNORE_WIDTH values to achieve the most appropriate non-exact string comparison. The IGNORE_KANATYPE and IGNORE_WIDTH values are ignored in non-Asian locales, so you can set these values for all locales and be guaranteed to have a culturally correct "insensitive" sorting regardless of the locale. Note that specifying these values slows performance, so use them only when necessary.

With a double-byte character set (DBCS) version of Windows, this function can compare two DBCS strings.

The Win32 lstrcmpi function uses a word sort, rather than a string sort. A word sort treats hyphens and apostrophes differently than it treats other symbols that are not alphanumeric, in order to ensure that words such as "coop" and "co-op" stay together within a sorted list. Note that in 16-bit versions of Windows, lstrcmpi uses a string sort. For a detailed discussion of word sorts and string sorts, see the Remarks section of the reference page for the CompareString function .

See Also

CompareString, lstrcat, lstrcmp, lstrcpy, lstrlen


lstrcpy

The lstrcpy function copies a string to a buffer.

LPTSTR lstrcpy(

LPTSTR  lpszString1,	// address of buffer
LPCTSTR  lpszString2	// address of string to copy
);
Parameters

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.

Return Value

If the function succeeds, the return value is a pointer to the buffer.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

With a double-byte character set (DBCS) version of Windows, this function can be used to copy a DBCS string.

See Also

lstrcat, lstrcmp, lstrcmpi, lstrlen


lstrcpyn

The lstrcpyn function copies a specified number of characters from a source string into a buffer.

LPTSTR lstrcpyn(

LPTSTR  lpszString1,	// address of target buffer
LPCTSTR  lpszString2,	// address of source string
int  cChars	// number of bytes or characters to copy
);
Parameters

lpszString1

Points to a buffer into which the function copies characters. The buffer must be large enough to contain the number of bytes (ANSI version) or characters (Unicode version) specified by cChars, plus have room for a terminating null character.

lpszString2

Points to a null-terminated string from which the function copies characters.

cChars

Specifies the number bytes (ANSI version) or characters (Unicode version) to be copied from the string pointed to by lpszString2 into the buffer pointed to by lpszString1.

Return Value

If the function succeeds, the return value is a pointer to the buffer.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

lstrcat, lstrcmp, lstrcmpi, lstrcpy, lstrlen


lstrlen

The lstrlen function returns the length in bytes (ANSI version) or characters (Unicode version) of the specified string (not including the terminating null character).

int lstrlen(

LPCTSTR  lpszString	// address of string to count
);
Parameters

lpszString

Points to a null-terminated string.

Return Value

If the function succeeds, the return value specifies the length of the string in bytes (ANSI version) or characters (Unicode version).

See Also

lstrcat, lstrcmp, lstrcmpi, lstrcpy


LZClose

The LZClose function closes a file that was opened by using the LZOpenFile function.

VOID LZClose(

INT  hFile	// LZ file handle identifying file to be closed
);
Parameters

hFile

Identifies the source file to be closed.

Return Value

This function does not return a value.

Remarks

The handle identifying the file must be retrieved by calling the LZOpenFile function. If the handle is retrieved by calling the CreateFile or OpenFile function, an error occurs.

If the file is compressed by using the Microsoft File Compression Utility (COMPRESS.EXE) and opened by using LZOpenFile, LZClose frees any global heap space that was allocated to expand the file.

See Also

CreateFile, LZOpenFile, OpenFile


LZCopy

The LZCopy function copies a source file to a destination file. If the source file is compressed with the Microsoft File Compression Utility (COMPRESS.EXE), this function creates a decompressed destination file. If the source file is not compressed, this function duplicates the original file.

LONG LZCopy(

INT  hfSource,	// LZ file handle identifying source file
INT  hfDest	// LZ file handle identifying destination file
);
Parameters

hfSource

Identifies the source file.

hfDest

Identifies the destination file.

Return Value

If the function succeeds, the return value specifies the size, in bytes, of the destination file.

If the function fails, the return value is an LZERROR_* code. These codes have values less than zero. Note that LZCopy calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread's last-error code.

Here is a list of the LZERROR_* codes that LZCopy can return upon failure:

Value	Meaning
LZERROR_BADINHANDLE	The handle identifying the source file is not valid. The file cannot be read.
LZERROR_BADOUTHANDLE	The handle identifying the destination file is not valid. The file cannot be written.
LZERROR_GLOBALLOC	The maximum number of open compressed files has been exceeded or local memory cannot be allocated.
LZERROR_GLOBLOCK	The LZ file handle cannot be locked down.
LZERROR_READ	The source file format is not valid.
Remarks

The handles identifying the source and destination files must be retrieved by calling the LZInit or LZOpenFile function.

The preferred function to use for copying files is LZCopy. The CopyLZFile function is provided for compatibility with 16-bit versions of Windows.

If the function succeeds, the file identified by the hfDest parameter is always uncompressed.

See Also

CopyLZFile, LZInit, LZOpenFile


LZDone

The LZDone function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the LZOpenFile function.


LZInit

The LZInit function allocates memory for the internal data structures required to decompress files, and then creates and initializes them.

INT LZInit(

INT  hfSource	// handle of source file
);
Parameters

hfSource

Identifies the source file.

Return Value

If the function succeeds, the return value is a new LZ file handle.

If the function fails, the return value is an LZERROR_* code. These codes have values less than zero. Note that LZInit calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread's last-error code.

Here is a list of the LZERROR_* codes that LZInit can return upon failure:

Value	Meaning
LZERROR_BADINHANDLE	The handle identifying the source file is not valid. The file cannot be read.
LZERROR_GLOBALLOC	The maximum number of open compressed files has been exceeded or local memory cannot be allocated.
LZERROR_GLOBLOCK	The LZ file handle cannot be locked down.
LZERROR_UNKNOWNALG	The file is compressed with an unrecognized compression algorithm.
Remarks

A maximum of 16 compressed files can be open at any given time. Similarly, a maximum of 16 uncompressed files can be open at any given time. An application should be careful to close the handle returned by LZInit when it is done using the file; otherwise, the application can inadvertently hit the 16-file limit.

The handle this function returns is compatible only with the functions in LZEXPAND.DLL; it should not be used for other file operations.


ObjectPrivilegeAuditAlarm

The ObjectPrivilegeAuditAlarm function generates audit messages as a result of a client's attempt to perform a privileged operation on a server application object using an already opened handle of that object. Alarms are not supported in the current version of Windows NT.

BOOL ObjectPrivilegeAuditAlarm(

LPCTSTR  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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The ObjectPrivilegeAuditAlarm function requires the calling process to have SE_AUDIT_NAME privilege. The test for this privilege is always performed against the primary token of the calling process, not the impersonation token of the thread. This allows the calling process to impersonate a client during the call.

The ObjectPrivilegeAuditAlarm function can send many messages to port objects. This can result in a significant delay before the function returns. The design of applications calling ObjectPrivilegeAuditAlarm can take this potential delay into account. For example, this consideration may affect the design of an application using mutexes to lock structures.

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, MapGenericMask, ObjectCloseAuditAlarm, ObjectOpenAuditAlarm, PrivilegeCheck, PrivilegedServiceAuditAlarm, PRIVILEGE_SET


OemKeyScan

The OemKeyScan function maps OEM ASCII codes 0 through 0x0FF into the OEM scan codes and shift states. The function provides information that allows a program to send OEM text to another program by simulating keyboard input.

DWORD OemKeyScan(

WORD  wOemChar	// ASCII value of OEM character
);
Parameters

wOemChar

Specifies the ASCII value of the OEM character.

Return Value

If the function succeeds, the low-order word of the return value contains the scan code of the given OEM character, and the high-order word contains the shift state, which can be a combination of the following flag bits:

Bit	Meaning
1	Either SHIFT key is pressed.
2	Either CTRL key is pressed.
4	Either ALT key is pressed.
If the character cannot be produced by a single keystroke using the current keyboard layout, the return value is 0xFFFFFFFF.

Remarks

This function does not provide translations for characters that require CTRL+ALT or dead keys. Characters not translated by this function must be copied by simulating input using the ALT+ keypad mechanism. The NUMLOCK key must be off.

This function does not provide translations for characters that cannot be typed with one keystroke using the current keyboard layout, such as characters with diacritics requiring dead keys. Characters not translated by this function may be simulated using the ALT+ keypad mechanism. The NUMLOCK key must be on.

This function is implemented using the VkKeyScan function.

See Also

VkKeyScan


OemToAnsi

The OemToAnsi function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the OemToChar function, which should be used for new Win32-based applications.


OemToAnsiBuff

The OemToAnsiBuff function is obsolete.

For compatibility with 16-bit versions of Windows, this function is implemented as a macro that calls the OemToCharBufffunction, which should be used for Win32-based applications.


OemToChar

The OemToChar function translates a string from the OEM-defined character set into either an ANSI or a wide-character string. (OEM stands for original equipment manufacturer.) This function supersedes the OemToAnsi function.

BOOL OemToChar(

LPCSTR  lpszOemStr,	// address of string to translate
LPTSTR  lpszStr	// address of buffer for translated string
);
Parameters

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.

Return Value

The return value is always TRUE.

See Also

CharToOem, CharToOemBuff, OemToCharBuff


OemToCharBuff

The OemToCharBuff function translates a specified number of characters in a string from the OEM-defined character set into either an ANSI or a wide-character string. (OEM stands for original equipment manufacturer.) This function supersedes the OemToAnsiBuff function.

BOOL OemToCharBuff(

LPCSTR  lpOemStr,	// address of string to translate
LPTSTR  lpszStr,	// address of buffer for translated string
DWORD  cchString	// size of buffer
);
Parameters

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.

Return Value

The return value is always TRUE.

See Also

CharToOem, CharToOemBuff, OemToChar


OffsetClipRgn

The OffsetClipRgn function moves the clipping region of a device context by the specified offsets.

int OffsetClipRgn(

HDC  hdc,	// handle of device context
int  nXOffset,	// offset along x-axis
int  nYOffset	// offset along y-axis
);
Parameters

hdc

Identifies the device context.

nXOffset

Specifies the number of logical units to move left or right.

nYOffset

Specifies the number of logical units to move up or down.

Return Value

If the function succeeds, the return value specifies the new region's complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred. (The current clipping region is unaffected.)
See Also

SelectClipRgn


OffsetRect

The OffsetRect function moves the specified rectangle by the specified offsets.

BOOL OffsetRect(

LPRECT  lprc,	// address of structure with rectangle
int  x,	// horizontal offset
int  y	// vertical offset
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

InflateRect, IntersectRect, UnionRect, RECT


OffsetRgn

The OffsetRgn function moves a region by the specified offsets.

int OffsetRgn(

HRGN  hrgn,	// handle of region
int  nXOffset,	// offset along x-axis
int  nYOffset	// offset along y-axis
);
Parameters

hrgn

Identifies the region to be moved.

nXOffset

Specifies the number of logical units to move left or right.

nYOffset

Specifies the number of logical units to move up or down.

Return Value

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.


OffsetViewportOrg

The OffsetViewportOrg function is not implemented in the Win32 API. Win32-based applications should use the OffsetViewportOrgEx function.


OffsetViewportOrgEx

The OffsetViewportOrgEx function modifies the viewport origin for a device context using the specified horizontal and vertical offsets.

BOOL OffsetViewportOrgEx(

HDC  hdc,	// handle of device context
int  nXOffset,	// horizontal offset
int  nYOffset,	// vertical offset
LPPOINT  lpPoint	// address of structure receiving original origin
);
Parameters

hdc

Identifies the device context.

nXOffset

Specifies the horizontal offset, in device units.

nYOffset

Specifies the vertical offset, in device units.

lpPoint

Points to a POINT structure. The previous viewport origin, in device units, is placed in this structure. If lpPoint is NULL, the previous viewport origin is not returned.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The new origin is the sum of the current origin and the horizontal and vertical offsets.

See Also

GetViewportOrgEx, OffsetWindowOrgEx, SetViewportOrgEx


OffsetWindowOrg

The OffsetWindowOrg function is not implemented in the Win32 API. Win32-based applications should use the OffsetWindowOrgEx function.


OffsetWindowOrgEx

The OffsetWindowOrgEx function modifies the window origin for a device context using the specified horizontal and vertical offsets.

BOOL OffsetWindowOrgEx(

HDC  hdc,	// handle of device context
int  nXOffset,	// horizontal offset
int  nYOffset,	// vertical offset
LPPOINT  lpPoint	// address of structure receiving the original origin
);
Parameters

hdc

Identifies the device context.

nXOffset

Specifies the horizontal offset, in logical units.

nYOffset

Specifies the vertical offset, in logical units.

lpPoint

Points to a POINT structure. The logical coordinates of the previous window origin are placed in this structure. If lpPoint is NULL, the previous origin is not returned.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

GetViewportOrgEx, OffsetViewportOrgEx, POINT


OpenBackupEventLog

The OpenBackupEventLog function opens a handle of a backup event log. This handle can be used with the BackupEventLog function.

HANDLE OpenBackupEventLog(

LPCTSTR  lpszUNCServerName,	// backup file server name
LPCTSTR  lpszFileName	// backup filename
);
Parameters

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, the lpszUNCServerName parameter must be NULL).

Return Value

If the function succeeds, the return value is a handle of the backup event log.

If the function fails, the return value is NULL.

Remarks

If the backup filename specifies a remote server, lpszUNCServerName must be NULL. You cannot use this function to open a file on a remote server.

See Also

BackupEventLog


OpenClipboard

The OpenClipboard function opens the clipboard for examination and prevents other applications from modifying the clipboard content.

BOOL OpenClipboard(

HWND  hwnd	// handle of window opening clipboard
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

OpenClipboard fails if another window has the clipboard open.

An application should call the CloseClipboard function after every successful call to OpenClipboard.

The window identified by the hwnd parameter does not become the clipboard owner unless the EmptyClipboard function is called.

See Also

CloseClipboard, EmptyClipboard


OpenDesktop  (preliminaryWindows NT)
OpenDesktop  (preliminary−Windows NT)

The OpenDesktop function returns a handle to an existing desktop. A desktop is a secure object contained within a window station object. A desktop has a logical display surface and contains windows, menus and hooks.

HDESK OpenDesktop(

LPCTSTR lpszDesktopName	// name of the desktop to open
DWORD dwFlags	// flags to control interaction with other applications
BOOL fInherit	// specifies whether returned handle is inheritable
DWORD dwDesiredAccess	// specifies access of returned handle
);
Parameters

lpszDesktopName

Points to null-terminated string specifying the name of the desktop to be opened. Desktop names are case-insensitive.

dwFlags

A bit flag parameter that controls how the calling application will cooperate with other applications on the desktop. This parameter can specify zero or the following value:

Value	Description
DF_ALLOWOTHERACCOUNTHOOK	Allows processes running in other accounts on the desktop to set hooks in this process.
fInherit

Specifies whether the returned handle is inherited when a new process is created. If this value is TRUE, new processes will inherit the handle.

dwDesiredAccess

Specifies the type of access to the desktop. This parameter can be one or more of the following values:

Value	Description
DESKTOP_CREATEMENU	Required to create a menu on the desktop.
DESKTOP_CREATEWINDOW	Required to create a window on the desktop.
DESKTOP_ENUMERATE	Required for the desktop to be enumerated.
DESKTOP_HOOKCONTROL	Required to establish any of the window hooks.
DESKTOP_JOURNALPLAYBACK	Required to perform journal playback on the desktop.
DESKTOP_JOURNALRECORD	Required to perform journal recording on the desktop.
DESKTOP_READOBJECTS	Required to read objects on the desktop.
DESKTOP_SWITCHDESKTOP	Required to activate the desktop using SwitchDesktop.
DESKTOP_WRITEOBJECTS	Required to write objects on the desktop.
Return Value

If the function succeeds, the return value is the handle to the opened desktop.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The calling process must have an associated window station, either assigned by the system at process creation time or set by the SetProcessWindowStation function.

See Also

CreateDesktop, SetProcessWindowStation, SetThreadDesktop, SwitchDesktop


OpenEvent

The OpenEvent function returns a handle of an existing named event object.

HANDLE OpenEvent(

DWORD  fdwAccess,	// access flag
BOOL  fInherit,	// inherit flag
LPCTSTR  lpszEventName	// address of event-object name
);
Parameters

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_ALL_ACCESS	Specifies all possible access flags for the event object.
EVENT_MODIFY_STATE	Enables use of the event handle in the SetEvent and ResetEvent functions to modify the event's state.
SYNCHRONIZE	Enables use of the event handle in any of the wait functions to wait for the event's state to be signaled.
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.

Return Value

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

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The OpenEvent function enables multiple processes to open handles of the same event object. The function succeeds only if some process has already created the event by using the CreateEvent function. The calling process can use the returned handle in any function that requires a handle of an event object, subject to the limitations of the access specified in the 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, CreateProcess, DuplicateHandle, MsgWaitForMultipleObjects, PulseEvent, ResetEvent, SetEvent, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


OpenEventLog

The OpenEventLog function opens a handle of an event log.

HANDLE OpenEventLog(

LPCTSTR  lpszUNCServerName,	// address of server name
LPCTSTR  lpszSourceName	// address of source name
);
Parameters

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.

Return Value

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

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

ClearEventLog, CloseEventLog, GetNumberOfEventLogRecords, GetOldestEventLogRecord, ReadEventLog, ReportEvent


OpenFile

The OpenFile function creates, opens, reopens, or deletes a file.

This function is provided for compatibility with 16-bit versions of Windows. In particular, the OpenFile function cannot open a named pipe. Win32-based applications should use the CreateFile function.

HFILE OpenFile(

LPCSTR  lpszFile,	// address of filename
LPOFSTRUCT  lpOpenBuff,	// address of buffer for file information
UINT  fuMode	// action and attributes
);
Parameters

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 that receives information about the file when it is first opened. The structure can be used in subsequent calls to the OpenFile function to refer to the open file.

The OFSTRUCT structure contains a pathname string member whose length is limited to OFS_MAXPATHNAME characters. OFS_MAXPATHNAME is currently defined to be 128. Because of this, you cannot use the OpenFile function to open a file whose path length exceeds 128 characters. The CreateFile function does not have such a path length limitation.

fuMode

Specifies the action to take. The following values can be combined by using the bitwise OR operator:

Value	Meaning
OF_CANCEL	Ignored. In the Win32 application programming interface (API), the OF_PROMPT style produces a dialog box containing a Cancel button.
OF_CREATE	Creates a new file. If the file already exists, it is truncated to zero length.
OF_DELETE	Deletes the file.
OF_EXIST	Opens the file and then closes it. Used to test for a file's existence.
OF_PARSE	Fills the OFSTRUCT structure but carries out no other action.
OF_PROMPT	Displays a dialog box if the requested file does not exist. The dialog box informs the user that Windows cannot find the file, and it contains Retry and Cancel buttons. Choosing the Cancel button directs OpenFile to return a file-not-found error message.
OF_READ	Opens the file for reading only.
OF_READWRITE	Opens the file for reading and writing.
OF_REOPEN	Opens the file using information in the reopen buffer.
OF_SHARE_COMPAT	For MS-DOS−based file systems using the Win32 API, opens the file with compatibility mode, allowing any process on a specified computer to open the file any number of times. Other efforts to open with any other sharing mode fail. On the Windows NT platform, this flag is mapped to the CreateFile function's FILE_SHARE_READ | FILE_SHARE_WRITE flags.
OF_SHARE_DENY_NONE	Opens the file without denying read or write access to other processes. On MS-DOS-based file systems using the Win32 API, if the file has been opened in compatibility mode by any other process, the function fails. On the Windows NT platform, this flag is mapped to the CreateFile function's FILE_SHARE_READ | FILE_SHARE_WRITE flags.
OF_SHARE_DENY_READ	Opens the file and denies read access to other processes. On MS-DOS-based file systems using the Win32 API, if the file has been opened in compatibility mode or for read access by any other process, the function fails.  On the Windows NT platform, this flag is mapped to the CreateFile function's FILE_SHARE_WRITE flag.
OF_SHARE_DENY_WRITE	Opens the file and denies write access to other processes. On MS-DOS-based file systems using the Win32 API, if the file has been opened in compatibility mode or for write access by any other process, the function fails.  On the Windows NT platform, this flag is mapped to the CreateFile function's FILE_SHARE_WRITE flag.
OF_SHARE_EXCLUSIVE	Opens the file with exclusive mode, denying both read and write access to other processes. If the file has been opened in any other mode for read or write access, even by the current process, the function fails.
OF_VERIFY	Verifies that the date and time of the file are the same as when it was previously opened. This is useful as an extra check for read-only files.
OF_WRITE	Opens the file for writing only.
Return Value

If the function succeeds, the return value specifies a file handle.

If the function fails, the return value is HFILE_ERROR. To get extended error information, call GetLastError.

Remarks

If the 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.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT only: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

The lpszFile parameter cannot contain wildcard characters.

To close the file after use, call the _lclose function.

See Also

CreateFile, GetSystemDirectory, GetWindowsDirectory, _lclose, OFSTRUCT


OpenFileMapping

The OpenFileMapping function opens a named file-mapping object.

HANDLE OpenFileMapping(

DWORD  dwDesiredAccess,	// access mode
BOOL  bInheritHandle,	// inherit flag
LPCTSTR  lpName	// address of name of file-mapping object
);
Parameters

dwDesiredAccess

Specifies the access to the file-mapping object.

Windows NT:

This access is checked against any security descriptor on the target file-mapping object.

Windows 95:

Windows 95 does not support security descriptors on file mapping objects.

This parameter can be one of the following values:

Value	Meaning
FILE_MAP_WRITE	Read-write access. The target file-mapping object must have been created with PAGE_READWRITE protection. A read-write view of the file is mapped.
FILE_MAP_READ	Read-only access. The target file-mapping object must have been created with PAGE_READWRITE or PAGE_READ protection. A read-only view of the file is mapped.
FILE_MAP_ALL_ACCESS	Same as FILE_MAP_WRITE.
FILE_MAP_COPY	Copy-on-write access. The target file-mapping object must have been created with PAGE_WRITECOPY protection. A copy-on-write view of the file is mapped.
bInheritHandle

Specifies whether the returned handle is to be inherited by a new process during process creation. A value of TRUE indicates that the new process inherits the handle.

lpName

Points to a string that names the file-mapping object to be opened. If there is an open handle to a file-mapping object by this name and the security descriptor on the mapping object does not conflict with the dwDesiredAccess parameter, the open operation succeeds.

Return Value

If the function succeeds, the return value is an open handle to the specified file-mapping object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The handle that OpenFileMapping returns can be used with any function that requires a handle to a file-mapping object.

See Also

CreateFileMapping


OpenIcon

The OpenIcon function restores a minimized (iconic) window to its previous size and position; it then activates the window.

BOOL OpenIcon(

HWND  hwnd	// handle of window
);
Parameters

hwnd

Identifies the window to be restored and activated.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

OpenIcon sends a WM_QUERYOPEN message to the given window.

See Also

CloseWindow, IsIconic, ShowWindow


OpenInputDesktop  (preliminaryWindows NT)
OpenInputDesktop  (preliminary−Windows NT)

The OpenInputDesktop function returns a handle to the desktop that receives user input. The input desktop is a desktop on the window station associated with the logged-on user.

HDESK OpenInputDesktop(

DWORD dwFlags	// flags to control interaction with other applications
BOOL fInherit	// specifies whether returned handle is inheritable
DWORD dwDesiredAccess	// specifies access of returned handle
);
Parameters

dwFlags

A bit flag parameter that controls how the calling application will cooperate with other applications on the desktop. This parameter can specify zero or the following value:

Value	Description
DF_ALLOWOTHERACCOUNTHOOK	Allows processes running in other accounts on the desktop to set hooks in this process.
fInherit

Specifies whether the returned handle is inherited when a new process is created. If this value is TRUE, new processes will inherit the handle.

dwDesiredAccess

Specifies the type of access to the desktop. This parameter can be one or more of the following values:

Value	Description
DESKTOP_CREATEMENU	Required to create a menu on the desktop.
DESKTOP_CREATEWINDOW	Required to create a window on the desktop.
DESKTOP_ENUMERATE	Required for the desktop to be enumerated.
DESKTOP_HOOKCONTROL	Required to establish any of the window hooks.
DESKTOP_JOURNALPLAYBACK	Required to perform journal playback on the desktop.
DESKTOP_JOURNALRECORD	Required to perform journal recording on the desktop.
DESKTOP_READOBJECTS	Required to read objects on the desktop.
DESKTOP_SWITCHDESKTOP	Required to activate the desktop using SwitchDesktop.
DESKTOP_WRITEOBJECTS	Required to write objects on the desktop.
Return Value

If the function succeeds, the return value is a handle of the desktop that receives user input.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The calling process must have an associated window station, either assigned by the system at process creation time or set by SetProcessWindowStation The window station associated with the calling process must be capable of receiving input.

An application can use the SwitchDesktop function to change the input desktop.

See Also

SetProcessWindowStation, SwitchDesktop


OpenMutex

The OpenMutex function returns a handle of an existing named mutex object.

HANDLE OpenMutex(

DWORD  fdwAccess,	// access flag
BOOL  fInherit,	// inherit flag
LPCTSTR  lpszMutexName	// address of mutex-object name
);
Parameters

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
MUTEX_ALL_ACCESS	Specifies all possible access flags for the mutex object.
SYNCHRONIZE	Windows NT: 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.
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.

Return Value

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

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The OpenMutex function enables multiple processes to open handles of the same mutex object. The function succeeds only if some process has already created the mutex by using the CreateMutex function. The calling process can use the returned handle in any function that requires a handle of a mutex object, 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, CreateProcess, DuplicateHandle, MsgWaitForMultipleObjects, ReleaseMutex, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject, WaitForSingleObjectEx


OpenPrinter

The OpenPrinter function retrieves a handle identifying the specified printer or print server.

BOOL OpenPrinter(

LPTSTR  pPrinterName,	// address of printer or server name
LPHANDLE  phPrinter,	// address of printer or server handle
LPPRINTER_DEFAULTS  pDefault	// address of printer defaults structure
);
Parameters

pPrinterName

Points to a null-terminated string that specifies the name of the printer or print server.

phPrinter

Points to a variable that receives the handle identifying the opened printer or print server object.

pDefault

Points to a PRINTER_DEFAULTS structure. This value can be NULL.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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 to call WaitForPrinterChange. To do so, it should call OpenPrinter with pPrinterName set to the name of the server and should specify a server access mask value such as SERVER_ALL_ACCESS. The pDatatype and pDevMode members of the PRINTER_DEFAULTS data structure should be set to NULL. The handle returned by such a call may be passed to the ClosePrinter or WaitForPrinterChange function.

If a user does not hold permission to open a specified printer or print server with the desired access, the OpenPrinter call will fail, and GetLastError will return the value ERROR_ACCESS_DENIED.

See Also

ClosePrinter, SetPrinter, StartDocPrinter, WaitForPrinterChange, PRINTER_DEFAULTS


OpenProcess

The OpenProcess function returns a handle of an existing process object.

HANDLE OpenProcess(

DWORD  fdwAccess,	// access flag
BOOL  fInherit,	// handle inheritance flag
DWORD  IDProcess	// process identifier
);
Parameters

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_ALL_ACCESS	Specifies all possible access flags for the process object.
PROCESS_CREATE_PROCESS	Used internally.
PROCESS_CREATE_THREAD	Enables using the process handle in the CreateRemoteThread function to create a thread in the process.
PROCESS_DUP_HANDLE	Enables using the process handle as either the source or target process in the DuplicateHandle function to duplicate a handle.
PROCESS_QUERY_INFORMATION	Enables using the process handle in the GetExitCodeProcess and GetPriorityClass functions to read information from the process object.
PROCESS_SET_INFORMATION	Enables using the process handle in the SetPriorityClass function to set the priority class of the process.
PROCESS_TERMINATE	Enables using the process handle in the TerminateProcess function to terminate the process.
PROCESS_VM_OPERATION	Enables using the process handle in the VirtualProtectEx and WriteProcessMemory functions to modify the virtual memory of the process.
PROCESS_VM_READ	Enables using the process handle in the ReadProcessMemory function to read from the virtual memory of the process.
PROCESS_VM_WRITE	Enables using the process handle in the WriteProcessMemory function to write to the virtual memory of the process.
SYNCHRONIZE	Windows NT: Enables using the process handle in any of the wait functions to wait for the process to terminate.
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.

Return Value

If the function succeeds, the return value is an open handle of the specified process.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The handle returned by the OpenProcess function can be used in any function that requires a handle to a process, provided the appropriate access rights were requested.

See Also

CreateProcess, CreateRemoteThread, DuplicateHandle, GetCurrentProcess, GetCurrentProcessId, GetExitCodeProcess, GetPriorityClass, ReadProcessMemory, SetPriorityClass, TerminateProcess, VirtualProtectEx, WriteProcessMemory,


OpenProcessToken

The OpenProcessToken function opens the access token associated with a process.

BOOL OpenProcessToken(

HANDLE  hProcess,	// handle of process
DWORD  dwAccessMask,	// desired access to process
PHANDLE  phToken	// address of handle of open access token
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AdjustTokenGroups, AdjustTokenPrivileges, GetTokenInformation, OpenThreadToken, SetTokenInformation


OpenSCManager

The OpenSCManager function establishes a connection to the service control manager on the specified computer and opens the specified database.

SC_HANDLE OpenSCManager(

LPCTSTR  lpszMachineName,	// address of machine name string
LPCTSTR  lpszDatabaseName,	// address of database name string
DWORD  fdwDesiredAccess	// type of access
);
Parameters

lpszMachineName

Points to a null-terminated string that names the target computer. If the pointer is NULL or if it points to an empty string, the function connects to the service control manager on the local computer.

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.
Return Value

If the function succeeds, the return value is a handle to the specified service control manager database.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Error code	Meaning
ERROR_ACCESS_DENIED	The requested access was denied.
ERROR_DATABASE_DOES_NOT_EXIST	The specified database does not exist.
ERROR_INVALID_PARAMETER	A parameter that was specified is invalid.
Remarks

When a process uses the OpenSCManager function to open a handle to a service control manager database, the system performs a security check before granting the requested access. All processes are permitted SC_MANAGER_CONNECT, SC_MANAGER_ENUMERATE_SERVICE, and SC_MANAGER_QUERY_LOCK_STATUS access to all service control manager databases. This enables any process to open a service control manager database handle that it can use in the OpenService, EnumServicesStatus, and QueryServiceLockStatus functions. Only processes with Administrator privileges are able to open a database handle used by the CreateService and LockServiceDatabase functions.

The calling process can use the returned handle to identify the database in the following functions, if the appropriate access rights are enabled:

CreateService
EnumServicesStatus
LockServiceDatabase
OpenService
QueryServiceLockStatus

The returned handle is only valid for the process that called the OpenSCManager function. It can be closed by calling the CloseServiceHandle function.

See Also

CloseServiceHandle, CreateService, EnumServicesStatus, LockServiceDatabase, OpenService, QueryServiceLockStatus


OpenSemaphore

The OpenSemaphore function returns a handle of an existing named semaphore object.

HANDLE OpenSemaphore(

DWORD  fdwAccess,	// access flag
BOOL  fInherit,	// inherit flag
LPCTSTR  lpszSemName	// address of semaphore-object name
);
Parameters

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_ALL_ACCESS	Specifies all possible access flags for the semaphore object.
SEMAPHORE_MODIFY_STATE	Enables use of the semaphore handle in the ReleaseSemaphore function to modify the semaphore's count.
SYNCHRONIZE	Windows NT: Enables use of the semaphore handle in any of the wait functions to wait for the semaphore's state to be signaled.
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.

Return Value

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

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The OpenSemaphore function enables multiple processes to open handles of the same semaphore object. The function succeeds only if some process has already created the semaphore by using the CreateSemaphore function. The calling process can use the returned handle in any function that requires a handle of a semaphore object, 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


OpenService

The OpenService function opens a handle to an existing service.

SC_HANDLE OpenService(

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
);
Parameters

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 slash (/), backslash (\), 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.
Return Value

If the function succeeds, the return value is a handle to the service.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Errors

The following error codes can be set by the service control manager. Others can be set by the registry functions that are called by the service control manager.

Error code	Meaning
ERROR_ACCESS_DENIED	The specified service control manager database handle does not have access to the service.
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_INVALID_NAME	The specified service name is invalid.
ERROR_SERVICE_DOES_NOT_EXIST	The specified service does not exist.
Remarks

The calling process can use the returned handle to identify the service in the following functions, if the appropriate access rights are enabled:

ChangeServiceConfig
ControlService
DeleteService
EnumDependentServices
QueryServiceConfig
QueryServiceObjectSecurity
QueryServiceStatus
SetServiceObjectSecurity
StartService

The returned handle is only valid for the process that called OpenService. It can be closed by calling the CloseServiceHandle function.

See Also

ChangeServiceConfig, ControlService, CreateService, DeleteService, EnumDependentServices, OpenSCManager, QueryServiceConfig, QueryServiceObjectSecurity, QueryServiceStatus, SetServiceObjectSecurity, StartService


OpenSound

The OpenSound function has been deleted.

See Also

Beep, MessageBeep


OpenThreadToken

The OpenThreadToken function opens the access token associated with a thread.

BOOL OpenThreadToken(

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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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, SetThreadToken, SetTokenInformation


OpenWindowStation  (preliminaryWindows NT)
OpenWindowStation  (preliminary−Windows NT)

The OpenWindowStation function returns a handle to an existing window station.

HWINSTA OpenWindowStation(

LPCTSTR lpszWinStaName,	// name of the window station to open
BOOL fInherit,	// specifies whether returned handle is inheritable
DWORD dwDesiredAccess	// specifies access of returned handle
);
Parameters

lpszWinStaName

Points to a null-terminated string specifying the name of the window station to be opened. Window station names are case-insensitive.

fInherit

Specifies whether the returned handle is inherited when a new process is created. If this value is TRUE, new processes will inherit the handle.

dwDesiredAccess

Specifies the type of access to the window station. This parameter can be one or more of the following values:

Value	Description
WINSTA_ACCESSCLIPBOARD	Required to use the clipboard.
WINSTA_ACCESSGLOBALATOMS	Required to manipulate global atoms.
WINSTA_CREATEDESKTOP	Required to create new desktop objects on the window station.
WINSTA_ENUMDESKTOPS	Required to enumerate existing desktop objects.
WINSTA_ENUMERATE	Required for the window station to be enumerated.
WINSTA_EXITWINDOWS	Required to successfully call the ExitWindows and ExitWindowsEx functions.
WINSTA_READATTRIBUTES	Required to read the attributes of a window station object.
WINSTA_READSCREEN	Required to access screen contents.
WINSTA_WRITEATTRIBUTES	Required to modify the attributes of a window station object.
Return Value

If the function succeeds, the return value is the handle to the specified window station.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

ExitWindows, ExitWindowsEx


OutputDebugString

The OutputDebugString function sends a string to the debugger for the current application.

VOID OutputDebugString(

LPCTSTR  lpszOutputString	// address of string to be displayed
);
Parameters

lpszOutputString

Points to the null-terminated string to be displayed.

Return Value

This function does not return a value.

Remarks

If the application has no debugger, the system debugger displays the string. If the application has no debugger and the system debugger is not active, OutputDebugString does nothing.


OutputProc

The OutputProc function is an application-defined callback function that draws a string as a result of a call to the GrayString function.

BOOL CALLBACK OutputProc(

HDC  hdc,	// handle of device context
LPARAM  lpData,	// address of string to be drawn
int  cchData	// length of string to be drawn
);
Parameters

hdc

Identifies a device context with a bitmap of at least the width and height specified by the nWidth and nHeight parameters passed to GrayString.

lpData

Points to the string to be drawn.

cchData

Specifies the length, in characters, of the string.

Return Value

If it succeeds, the callback function should return TRUE.

If the function fails, the return value is FALSE.

Remarks

The callback function must draw an image relative to the coordinates (0,0).

OutputProc is a placeholder for the application-defined function name.

See Also

GrayString


PackDDElParam

The PackDDElParam function packs a DDE lParam value into an internal structure used for sharing DDE data between processes.

LONG PackDDElParam(

UINT  uMsg,	// DDE message to be posted
UINT  uLow,	// low-order word of lParam of message
UINT  uHigh	// high-order word of lParam of message
);
Parameters

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.

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The return value must be posted as the lParam parameter of a DDE message; it must not be used for any other purpose. Once the application posts a return value, it need not perform any action to dispose of the lParam parameter.

PackDDElParam eases the porting of 16-bit DDE applications to 32-bit DDE applications.

An application should call this function only for posted DDE messages.

See Also

FreeDDElParam, ReuseDDElParam, UnpackDDElParam


PaintDesktop  (preliminaryWindows 95)
PaintDesktop  (preliminary−Windows 95)

The PaintDesktop function fills the clipping region in the specified device context with the desktop pattern or wallpaper. The function is provided primarily for shell desktops.

BOOL WINAPI PaintDesktop(

HDC hdc	\\
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


PaintRgn

The PaintRgn function paints the specified region by using the brush currently selected into the device context.

BOOL PaintRgn(

HDC  hdc,	// handle of device context
HRGN  hrgn	// handle of region to be painted
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region to be filled. The region's coordinates are presumed to be logical coordinates.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

FillRgn


PatBlt

The PatBlt function paints the given rectangle using the brush that is currently selected into the specified device context. The brush color and the surface color(s) are combined by using the given raster operation.

BOOL PatBlt(

HDC  hdc,	// handle 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
);
Parameters

hdc

Identifies the device context.

nXLeft

Specifies the x-coordinate, in logical units, of the upper-left corner of the rectangle to be filled.

nYLeft

Specifies the y-coordinate, in logical units, of the upper-left corner of the rectangle to be filled.

nWidth

Specifies the width, in logical units, of the rectangle.

nHeight

Specifies the height, in logical units, of the rectangle.

dwRop

Specifies the raster operation code. This code may be one of the following values:

Value	Meaning
PATCOPY	Copies the specified pattern into the destination bitmap.
PATINVERT	Combines the colors of the specified pattern with the colors of the destination rectangle by using the Boolean OR operator.
DSTINVERT	Inverts the destination rectangle.
BLACKNESS	Fills the destination rectangle using the color associated with index 0 in the physical palette. (This color is black for the default physical palette.)
WHITENESS	Fills the destination rectangle using the color associated with index 1 in the physical palette. (This color is white for the default physical palette.)
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The values of the dwRop parameter for this function are a limited subset of the full 256 ternary raster-operation codes; in particular, an operation code that refers to a source rectangle cannot be used.

Not all devices support the PatBlt function. For more information, see the description of the RC_BITBLT capability in the GetDeviceCaps function.

See Also

GetDeviceCaps


PathToRegion

The PathToRegion function creates a region from the path that is selected into the specified device context.

HRGN PathToRegion(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies a device context that contains a closed path.

Return Value

If the function succeeds, the return value identifies a valid region.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

The device context identified by the hdc parameter must contain a closed path.

After PathToRegion converts a path into a region, Windows discards the closed path from the specified device context.

See Also

BeginPath, EndPath , SetPolyFillMode,


PeekConsoleInput

The PeekConsoleInput function reads data from the specified console input buffer without removing it from the buffer.

BOOL PeekConsoleInput(

HANDLE  hConsoleInput,	// handle 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
);
Parameters

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

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the 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

INPUT_RECORD, ReadConsoleInput, WriteConsoleInput


PeekMessage

The PeekMessage function checks a thread message queue for a message and places the message (if any) in the specified structure.

BOOL PeekMessage(

LPMSG  lpMsg,	// address of structure for message
HWND  hWnd,	// handle of window
UINT  uMsgFilterMin,	// first message
UINT  uMsgFilterMax,	// last message
UINT  wRemoveMsg	// removal flags
);
Parameters

lpMsg

Points to an MSG structure that contains message information from the Windows-based application queue.

hWnd

Identifies the window whose messages are to be examined.

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.

wRemoveMsg

Specifies how messages are handled. This parameter can be one of the following values:

Value	Meaning
PM_NOREMOVE	Messages are not removed from the queue after processing by PeekMessage.
PM_REMOVE	Messages are removed from the queue after processing by PeekMessage.
You can optionally combine the value PM_NOYIELD with either PM_NOREMOVE or PM_REMOVE. However, PM_NOYIELD has no effect on 32-bit Windows applications. It is defined in Win32 solely to provide compatibility with applications written for previous versions of Windows, where it was used to prevent the current task from halting and yielding system resources to another task. 32-bit Windows applications always run simultaneously.

Return Value

If a message is available, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Unlike the GetMessage function, the PeekMessage function does not wait for a message to be placed in the queue before returning.

PeekMessage retrieves only messages associated with the window identified by the hWnd parameter or any of its children as specified by the IsChild function, and within the range of message values given by the 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 (that is, no range filtering is performed).

The WM_KEYFIRST and WM_KEYLAST constants can be used as filter values to retrieve all keyboard messages; the WM_MOUSEFIRST and WM_MOUSELAST constants can be used to retrieve all mouse messages.

The PeekMessage function normally does not remove WM_PAINT messages from the queue. WM_PAINT messages remain in the queue until they are processed. However, if a WM_PAINT message has a null update region, PeekMessage does remove it from the queue.

See Also

GetMessage, IsChild, MSG, PostAppMessage, WaitMessage


PeekNamedPipe

The PeekNamedPipe function copies data from a named or anonymous pipe into a buffer without removing it from the pipe. It also returns information about data in the pipe.

BOOL PeekNamedPipe(

HANDLE  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
);
Parameters

hPipe

Identifies the pipe. This parameter can be a handle to a named pipe instance, as returned by the CreateNamedPipe or CreateFile function, or it can be a handle to the read end of an anonymous pipe, as returned by the CreatePipe function. The handle must have GENERIC_READ access to the pipe.

lpvBuffer

Points to a buffer that receives data read from the pipe. This parameter can be NULL if no data is to be read.

cbBuffer

Specifies the size, in bytes, of the buffer specified by the lpvBuffer parameter. This parameter is ignored if lpvBuffer is NULL.

lpcbRead

Points to a 32-bit variable that receives the number of bytes read from the pipe. This parameter can be NULL if no data is to be read.

lpcbAvail

Points to a 32-bit variable that receives the total number of bytes available to be read from the pipe. This parameter can be NULL if no data is to be read.

lpcbMessage

Points to a 32-bit variable that receives the number of bytes remaining in this message. This parameter will be zero for byte-type named pipes or for anonymous pipes. This parameter can be NULL if no data is to be read.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

PeekNamedPipe is similar to the ReadFile function with the following exceptions:

•	The data read from the pipe is not removed from the pipe's buffer.

•	The function always returns immediately, even if there is no data in the pipe. The wait mode of a named pipe handle (blocking or nonblocking) has no effect on the function.

•	The function can return additional information about the contents of the pipe.

If the specified handle is a named pipe handle in byte-read mode, the function reads all available bytes up to the size specified in 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


Pie

The Pie function draws a pie-shaped wedge bounded by the intersection of an ellipse and two radials. The pie is outlined by using the current pen and filled by using the current brush.

BOOL Pie(

HDC  hdc,	// handle of device context
int  nLeftRect,	// x-coord. of bounding rectangle's upper-left corner
int  nTopRect,	// y-coord. of bounding rectangle's upper-left corner
int  nRightRect,	// x-coord. of bounding rectangle's lower-right corner
int  nBottomRect,	// y-coord. of bounding rectangle's lower-right corner
int  nXRadial1,	// x-coord. of first radial's endpoint
int  nYRadial1,	// y-coord. of first radial's endpoint
int  nXRadial2,	// x-coord. of second radial's endpoint
int  nYRadial2	// y-coord. of second radial's endpoint
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the x-coordinate of the upper-left corner of the bounding rectangle.

nTopRect

Specifies the y-coordinate of the upper-left corner of the bounding rectangle.

nRightRect

Specifies the x-coordinate of the lower-right corner of the bounding rectangle.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the bounding rectangle.

nXRadial1

Specifies the x-coordinate of the endpoint of the first radial.

nYRadial1

Specifies the y-coordinate of the endpoint of the first radial.

nXRadial2

Specifies the x-coordinate of the endpoint of the second radial.

nYRadial2

Specifies the y-coordinate of the endpoint of the second radial.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The curve of the pie is defined by an ellipse that fits the specified bounding rectangle. The curve begins at the point where the ellipse intersects the first radial and extends counterclockwise to the point where the ellipse intersects the second radial. (A radial is a line drawn from the center of the ellipse to the specified endpoint on the ellipse.)

The current position is neither used nor updated by the Pie function.

See Also

AngleArc, Arc, ArcTo, Chord


PlayEnhMetaFile

The PlayEnhMetaFile function displays the picture stored in the specified enhanced-format metafile.

BOOL PlayEnhMetaFile(

HDC  hdc,	// handle of a device context
HENHMETAFILE  hemf,	// handle of an enhanced metafile
CONST RECT *  lpRect	// address of bounding rectangle
);
Parameters

hdc

Identifies the device context for the output device on which the picture will appear.

hemf

Identifies the enhanced metafile.

lpRect

Points to a RECT structure that contains the coordinates of the bounding rectangle used to display the picture. The coordinates are specified in logical units.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

When 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, RECT, SetWorldTransform


PlayEnhMetaFileRecord

The PlayEnhMetaFileRecord function plays an enhanced-metafile record by executing the graphics device interface (GDI) functions identified by the record.

BOOL PlayEnhMetaFileRecord(

HDC  hdc,	// handle of device context
LPHANDLETABLE  lpHandletable,	// address of metafile handle table
CONST ENHMETARECORD *  lpEnhMetaRecord,	// address of metafile record
UINT  nHandles	// count of handles
);
Parameters

hdc

Identifies the device context passed to the EnumEnhMetaFile function.

lpHandletable

Points to a table of handles identifying GDI objects used when playing the metafile. The first entry in this table contains the enhanced-metafile handle.

lpEnhMetaRecord

Points to the enhanced-metafile record to be played.

nHandles

Specifies the number of handles in the handle table.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

This is an enhanced-metafile function.

An application typically uses PlayEnhMetaFileRecord in conjunction with the EnumEnhMetaFile function to process and play an enhanced-format metafile one record at a time.

The hdc, lpHandletable, and nHandles parameters must be exactly those passed to the EnhMetaFileProc callback procedure by the EnumEnhMetaFile function.

If PlayEnhMetaFileRecord does not recognize a record, it ignores the record and returns TRUE.

See Also

EnumEnhMetaFile, PlayEnhMetaFile


PlayMetaFile

The PlayMetaFile function displays the picture stored in the given Windows-format metafile on the specified device.

This function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should use the PlayEnhMetaFile function.

BOOL PlayMetaFile(

HDC  hdc,	// handle of the device context
HMETAFILE  hmf	// handle of the metafile
);
Parameters

hdc

Identifies a device context.

hmf

Identifies a Windows-format metafile.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced-format metafile functions.

To convert a Windows-format metafile into an enhanced format metafile, use the SetWinMetaFileBits function.

A Windows-format metafile can be played multiple times.

A Windows-format metafile can be embedded in a second Windows-format metafile by calling the PlayMetaFile function and playing the source metafile into the device context for the target metafile.

Any object created but not deleted in the Windows-format metafile is deleted by this function.

To stop this function, an application can call the CancelDC function from another thread to terminate the operation. In this case, the function returns FALSE.

See Also

BeginPath, CancelDC, PolyBezier, SetWinMetaFileBits, SetWorldTransform


PlayMetaFileRecord

The PlayMetaFileRecord function plays a Windows-format metafile record by executing the graphics device interface (GDI) function contained within that record.

This function is provided for compatibility with 16-bit versions of Microsoft Windows. Win32-based applications should use the PlayEnhMetaFileRecord function.

BOOL PlayMetaFileRecord(

HDC  hdc,	// handle of device context
LPHANDLETABLE  lpHandletable,	// address of metafile handle table
LPMETARECORD  lpMetaRecord,	// address of metafile record
UINT  nHandles	// count of handles
);
Parameters

hdc

Identifies a device context.

lpHandletable

Points to a table of handles identifying GDI objects used when playing the metafile.

lpMetaRecord

Points to the Windows-format metafile record.

nHandles

Specifies the number of handles in the handle table.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions, such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions, should use the enhanced format metafile functions.

To convert a Windows-format metafile into an enhanced-format metafile, use the SetWinMetaFileBits function.

An application typically uses PlayMetaFileRecord in conjunction with the EnumMetaFile function to process and play a Windows-format metafile one record at a time.

The lpHandletable and nHandles parameters must be identical to those passed to the EnumMetaFileProc callback procedure by EnumMetaFile.

If the PlayMetaFileRecord function does not recognize a record, it ignores the record and returns TRUE.

See Also

BeginPath, EnumMetaFile, PlayMetaFile, PolyBezier, SetWinMetaFileBits, SetWorldTransform


PlgBlt

The PlgBlt function performs a bit-block transfer of the bits of color data from the specified rectangle in the source device context to the specified parallelogram in the destination device context. If the given bitmask handle identifies a valid monochrome bitmap, the function uses this bitmap to mask the bits of color data from the source rectangle.

BOOL PlgBlt(

HDC  hdcDest,	// handle of destination device context
CONST POINT *  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.
);
Parameters

hdcDest

Identifies the destination device context.

lpPoint

Points to an array of three points in logical space that identify three corners of the destination parallelogram. The upper-left corner of the source rectangle is mapped to the first point in this array, the upper-right corner to the second point in this array, and the lower-left corner to the third point. The lower-right corner of the source rectangle is mapped to the implicit fourth point in the parallelogram.

hdcSrc

Identifies the source device context.

nXSrc

Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle.

nYSrc

Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle.

nWidth

Specifies the width, in logical units, of the source rectangle.

nHeight

Specifies the height, in logical units, of the source rectangle.

hbmMask

Identifies an optional monochrome bitmap that is used to mask the colors of the source rectangle.

xMask

Specifies the x-coordinate of the upper-left corner of the the monochrome bitmap.

yMask

Specifies the y-coordinate of the upper-left corner of the the monochrome bitmap.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The fourth vertex of the parallelogram (D) is defined by treating the first three points (A, B, and C) as vectors and computing D = B + C − A.

If the bitmask exists, a value of 1 in the mask indicates that the source pixel color should be copied to the destination. A value of 0 in the mask indicates that the destination pixel color is not to be changed.

If the mask rectangle is smaller than the source and destination rectangles, the function replicates the mask pattern.

Scaling, translation, and reflection transformations are allowed in the source device context; however, rotation and shear transformations are not.

If the mask bitmap is not a monochrome bitmap, an error occurs.

The stretching mode for the destination device context is used to determine how to stretch or compress the pixels, if that is necessary.

When an enhanced metafile is being recorded, an error occurs if the source device context identifies an enhanced-metafile device context.

The destination coordinates are transformed according to the destination device context; the source coordinates are transformed according to the source device context. If the source transformation has a rotation or shear, an error is returned.

If the destination and source rectangles do not have the same color format, PlgBlt converts the source rectangle to match the destination rectangle.

Not all devices support the PlgBlt function. For more information, see the description of the RC_BITBLT raster capability in the GetDeviceCaps function.

If the source and destination device contexts represent incompatible devices, PlgBlt returns an error.

See Also

BitBlt, GetDeviceCaps, MaskBlt, SetStretchBltMode, StretchBlt


PolyBezier

The PolyBezier function draws one or more Bézier curves.

BOOL PolyBezier(

HDC  hdc,	// handle of device context
CONST POINT *  lppt,	// address of endpoints and control points
DWORD  cPoints	// count of endpoints and control points
);
Parameters

hdc

Identifies a device context.

lppt

Points to an array of POINT structures that contain the endpoints and control points of the curve(s).

cPoints

Specifies the number of points in the lppt array. This value must be one more than three times the number of curves to be drawn, because each Bézier curve requires two control points and an endpoint, and the initial curve requires an additional starting point.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Th Polybezier function draws cubic Bézier curves by using the endpoints and control points specified by the lppt parameter. The first curve is drawn from the first point to the fourth point by using the second and third points as control points. Each subsequent curve in the sequence needs exactly three more points: the ending point of the previous curve is used as the starting point, the next two points in the sequence are control points, and the third is the ending point.

The current position is neither used nor updated by the PolyBezier function. The figure is not filled.

This function draws lines by using the current pen.

See Also

MoveToEx, POINT, PolyBezierTo


PolyBezierTo

The PolyBezierTo function draws one or more Bézier curves.

BOOL PolyBezierTo(

HDC  hdc,	// handle of device context
CONST POINT *  lppt,	// address of endpoints and control points
DWORD  cCount	// count of endpoints and control points
);
Parameters

hdc

Identifies a device context.

lppt

Points to an array of POINT structures that contains the endpoints and control points.

cCount

Specifies the number of points in the lppt array. This value must be three times the number of curves to be drawn, because each Bézier curve requires two control points and an ending point.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

This function draws cubic Bézier curves by using the control points specified by the lppt parameter. The first curve is drawn from the current position to the third point by using the first two points as control points. For each subsequent curve, the function needs exactly three more points, and uses the ending point of the previous curve as the starting point for the next.

PolyBezierTo moves the current position to the ending point of the last Bézier curve. The figure is not filled.

This function draws lines by using the current pen.

See Also

MoveToEx, POINT, PolyBezier


PolyDraw

The PolyDraw function draws a set of line segments and Bézier curves.

BOOL PolyDraw(

HDC  hdc,	// handle 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
);
Parameters

hdc

Identifies a device context.

lppt

Points to an array of POINT structures that contains the endpoints for each line segment and the endpoints and control points for each Bézier curve.

lpbTypes

Points to an array that specifies how each point in the lppt array is used. Types can be one of the following:

Type	Meaning
PT_MOVETO	Specifies that this point starts a disjoint figure. This point becomes the new current position.
PT_LINETO	Specifies that a line is to be drawn from the current position to this point, which then becomes the new current position.
PT_BEZIERTO	Specifies that this point is a control point or ending point for a Bézier curve.
	PT_BEZIERTO types always occur in sets of three. The current position defines the starting point for the Bézier curve. The first two PT_BEZIERTO points are the control points, and the third PT_BEZIERTO point is the ending point. The ending point becomes the new current position. If there are not three consecutive PT_BEZIERTO points, an error results.
A PT_LINETO or PT_BEZIERTO type can be combined with the following value by using the bitwise operator OR to indicate that the corresponding point is the last point in a figure and the figure is closed:

Value	Meaning
PT_CLOSEFIGURE	Specifies that the figure is automatically closed after the PT_LINETO or PT_BEZIERTO type for this point is done. A line is drawn from this point to the most recent PT_MOVETO or MoveTo point.
	This value is combined with the PT_LINETO type for a line, or with the PT_BEZIERTO type of the ending point for a Bézier curve, by using the bitwise operator OR.
	The current position is set to the ending point of the closing line.
cCount

Specifies the total number of points in the lppt array, the same as the number of bytes in the lpbTypes array.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The PolyDraw function can be used in place of consecutive calls to MoveTo, LineTo, and PolyBezierTo functions to draw disjoint figures. The lines and curves are drawn using the current pen and figures are not filled. If there is an active path started by calling BeginPath, PolyDraw adds to the path.

The points contained in the lppt array and in the lpbTypes array indicate whether each point is part of a MoveTo, LineTo, or PolyBezierTo operation. It is also possible to close figures.

This function updates the current position.

See Also

BeginPath, EndPath, LineTo, MoveTo, POINT, PolyBezierTo, PolyLine


Polygon

The Polygon function draws a polygon consisting of two or more vertices connected by straight lines. The polygon is outlined by using the current pen and filled by using the current brush and polygon fill mode.

BOOL Polygon(

HDC  hdc,	// handle of device context
CONST POINT  *lpPoints,	// address of polygon's vertices
int  nCount	// count of polygon's vertices
);
Parameters

hdc

Identifies the device context.

lpPoints

Points to an array of POINT structures that specify the vertices of the polygon.

nCount

Specifies the number of vertices in the array. This value must be greater than or equal to 2.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The polygon is closed automatically by drawing a line from the last vertex to the first.

The current position is neither used nor updated by the Polygon function.

See Also

GetPolyFillMode, POINT, Polyline, PolylineTo, PolyPolygon, SetPolyFillMode


Polyline

The Polyline function draws a series of line segments by connecting the points in the specified array.

BOOL Polyline(

HDC  hdc,	// handle of device context
CONST POINT  *lppt,	// address of array containing endpoints
int  cPoints	// number of points in the array
);
Parameters

hdc

Identifies a device context.

lppt

Points to an array of POINT structures. Each structure in the array identifies a point in logical space.

cPoints

Specifies the number of points in the array. This number must be greater than or equal to two.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The lines are drawn from the first point through subsequent points by using the current pen. Unlike the LineTo function, the Polyline function neither uses nor updates the current position.

See Also

LineTo, MoveToEx, POINT, PolylineTo, PolyPolyline


PolylineTo

The PolylineTo function draws one or more straight lines.

BOOL PolylineTo(

HDC  hdc,	// handle of device context
CONST POINT *  lppt,	// address of array of points
DWORD  cCount	// number of points in array
);
Parameters

hdc

Identifies the device context.

lppt

Points to an array of POINT structures that contains the vertices of the line.

cCount

Specifies the number of points in the array.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

A line is drawn from the current position to the first point specified by the lppt parameter by using the current pen. For each additional line, the function draws from the ending point of the previous line to the next point specified by lppt.

PolylineTo moves the current position to the ending point of the last line.

If the line segments drawn by this function form a closed figure, the figure is not filled.

See Also

LineTo, MoveToEx, POINT, Polyline


PolyPolygon

The PolyPolygon function draws a series of closed polygons. Each polygon is outlined by using the current pen and filled by using the current brush and polygon fill mode. The polygons drawn by this function can overlap.

BOOL PolyPolygon(

HDC  hdc,	// handle of device context
CONST POINT  *lpPoints,	// points to array of vertices for all polygons
LPINT  lpPolyCounts,	// points to array with count of vertices for each polygon
int  nCount	// count of polygons
);
Parameters

hdc

Identifies the device context.

lpPoints

Points to an array of POINT structures that define the vertices of the polygons. The polygons are specified consecutively. Each polygon is closed automatically by drawing a line from the last vertex to the first. Each vertex should be specified once.

lpPolyCounts

Points to an array of integers, each of which specifies the number of points in the corresponding polygon. Each integer must be greater than or equal to 2.

nCount

Specifies the total number of polygons.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The current position is neither used nor updated by this function.

See Also

GetPolyFillMode, POINT, Polygon, Polyline, PolylineTo, SetPolyFillMode


PolyPolyline

The PolyPolyline function draws multiple series of connected line segments.

BOOL PolyPolyline(

HDC  hdc,	// handle of a device context
CONST POINT *  lppt,	// address of an array of points
CONST DWORD *  lpdwPolyPoints,	// address of an array of values
DWORD  cCount	// number of counts in the second array
);
Parameters

hdc

Identifies the device context.

lppt

Points to an array of POINT structures that contains the vertices of the polylines. The polylines are specified consecutively.

lpdwPolyPoints

Points to an array of variables specifying the number of points in the lppt array for the corresponding polygon. Each entry must be greater than or equal to two.

cCount

Specifies the total number of counts in the lpdwPolyPoints array.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The line segments are drawn by using the current pen. The figures formed by the segments are not filled.

The current position is neither used nor updated by this function.

See Also

POINT, Polyline, PolylineTo


PolyTextOut

The PolyTextOut function draws several strings using the font and text colors currently selected in the specified device context.

BOOL PolyTextOut(

HDC  hdc,	// handle of device context
CONST POLYTEXT *  pptxt,	// address of array of structures that identify strings
int  cStrings	// number of structures in array
);
Parameters

hdc

Identifies the device context.

pptxt

Points to an array of POLYTEXT structures describing the strings to be drawn. The array contains one structure for each string to be drawn.

cStrings

Specifies the number of POLYTEXT structures in the pptxt array.

Return Value

If the function is successful, the return value is TRUE.

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

Remarks

Each POLYTEXT structure contains the coordinates of a reference point that Windows uses to align the corresponding string of text. An application can specify how the reference point is used by calling the SetTextAlign function. An application can determine the current text-alignment setting for the specified device context by calling the GetTextAlign function.

To draw a single string of text, the application should call the ExtTextOut function.

See Also

ExtTextOut, GetTextAlign, POLYTEXT, SetTextAlign


PostAppMessage

The PostAppMessage function is retained only for compatibility with 16-bit versions of Windows. Win32-based applications should use the PostThreadMessage function.

Remarks

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


PostMessage

The PostMessage function places (posts) a message in the message queue associated with the thread that created the specified window and then returns without waiting for the thread to process the message. Messages in a message queue are retrieved by calls to the GetMessage or PeekMessage function.

BOOL PostMessage(

HWND  hwnd,	// handle of destination window
UINT  uMsg,	// message to post
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hwnd

Identifies the window whose window procedure is to receive the message. Two values have special meanings:

Value	Meaning
HWND_BROADCAST	The message is posted to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows. The message is not posted to child windows.
NULL	The function behaves like a call to PostThreadMessage with the dwThreadId parameter set to the identifier of the current thread.
uMsg

Specifies the message to be posted.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A 32-bit application should not post messages less than WM_USER that contain pointers.

See Also

GetMessage, PeekMessage, PostThreadMessage, SendDlgItemMessage, SendMessage


PostQueuedCompletionStatus  (preliminaryWindows NT)
PostQueuedCompletionStatus  (preliminary−Windows NT)

The PostQueuedCompletionStatus function lets you post an I/O completion packet to an I/O completion port. The I/O completion packet will satisfy an outstanding call to the GetQueuedCompletionStatus function. The GetQueuedCompletionStatus function returns with the three values passed as the second, third, and fourth parameters of the call to PostQueuedCompletionStatus.

BOOL PostQueuedCompletionStatus(

HANDLE CompletionPort,	// handle to an I/O completion port
DWORD dwNumberOfBytesTransferred,	// value to return via  //     GetQueuedCompletionStatus'  //     lpNumberOfBytesTranferred
DWORD dwCompletionKey,	// value to return via  //     GetQueuedCompletionStatus'  //     lpCompletionKey
LPOVERLAPPED lpOverlapped	// value to return via  //     GetQueuedCompletionStatus' lpOverlapped
);
Parameters

CompletionPort

Handle to an I/O completion port that you want to post an I/O completion packet to.

dwNumberOfBytesTransferred

Specifies a value to be returned through the lpNumberOfBytesTransferred parameter of the GetQueuedCompletionStatus function.

dwCompletionKey

Specifies a value to be returned through the lpCompletionKey parameter of the GetQueuedCompletionStatus function.

lpOverlapped

Specifies a value to be returned through the lpOverlapped parameter of the GetQueuedCompletionStatus function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

For more information concerning dwNumberOfBytesTransferred, dwCompletionKey, and lpOverlapped, see GetQueuedCompletionStatus and the descriptions of the parameters those values are returned through.

See Also

CreateIoCompletionPort, GetQueuedCompletionStatus, OVERLAPPED


PostQuitMessage

The PostQuitMessage function indicates to Windows that a thread has made a request to terminate (quit). It is typically used in response to a WM_DESTROY message.

VOID PostQuitMessage(

int  nExitCode	// exit code
);
Parameters

nExitCode

Specifies an application exit code. This value is used as the wParam parameter of the WM_QUIT message.

Return Value

This function does not return a value.

Remarks

The PostQuitMessage function posts a WM_QUIT message to the thread's message queue and returns immediately; the function simply indicates to the system that the thread is requesting to quit at some time in the future.

When the thread retrieves the WM_QUIT message from its message queue, it should exit its message loop and return control to Windows. The exit value returned to Windows must be the wParam parameter of the WM_QUIT message.

See Also

GetMessage, PeekMessage, PostMessage, WM_DESTROY, WM_QUIT


PostThreadMessage

The PostThreadMessage function places (posts) a message in the message queue of the specified thread and then returns without waiting for the thread to process the message.

BOOL PostThreadMessage(

DWORD  dwThreadId,	// thread identifier
UINT  uMsg,	// message to post
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

dwThreadId

Identifies the thread to which the message will be posted.

uMsg

Specifies the type of message to be posted.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

This function replaces the PostAppMessage function. New Win32-based applications should use PostThreadMessage. The thread to which the message is posted retrieves the message by calling the GetMessage or PeekMessage function. The hwnd member of the returned MSG structure is NULL.

See Also

GetCurrentThreadId, GetMessage, GetWindowThreadProcessId, MSG, PeekMessage, PostMessage


PrepareTape

The PrepareTape function prepares the tape to be accessed or removed.

DWORD PrepareTape(

HANDLE  hDevice,	// handle of open device
DWORD  dwOperation,	// preparation method
BOOL  bImmediate	// return after operation begins
);
Parameters

hDevice

Identifies the device preparing the tape. This handle is created by using the CreateFile function.

dwOperation

Specifies how the tape device is to be prepared. This parameter can be one of the following values:

Value	Meaning
TAPE_FORMAT	Performs a low-level format of the tape. Currently, only the QIC117 device supports this feature.
TAPE_LOAD	Loads the tape and moves the tape to the beginning.
TAPE_LOCK	Locks the tape ejection mechanism so that the tape is not ejected accidentally.
TAPE_TENSION	Adjusts the tension by moving the tape to the end of the tape and back to the beginning. This option is not supported by all devices. This value is ignored if it is not supported.
TAPE_UNLOAD	Moves the tape to the beginning for removal from the device. After a successful unload operation, the device returns errors to applications that attempt to access the tape, until the tape is loaded again.
TAPE_UNLOCK	Unlocks the tape ejection mechanism.
bImmediate

Specifies whether to return as soon as the preparation begins. If this parameter is TRUE, the function returns immediately. If it is FALSE, the function does not return until the operation has been completed.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes:

Error	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

Some tape devices do not support certain tape operations. See your tape device documentation and use the GetTapeParameters function to determine your tape device's capabilities.

See Also

CreateFile, GetTapeParameters


PrintDlg

The PrintDlg function displays a Print dialog box or a Print Setup dialog box. The Print dialog box enables the user to specify the properties of a particular print job. The Print Setup dialog box allows the user to select additional job properties and to configure the printer.

BOOL PrintDlg(

LPPRINTDLG  lppd	// address of structure with initialization data
);
Parameters

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.

Return Value

If the function succeeds in configuring the printer, 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 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.)

The CommDlgExtendedError function can be used to get 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
Remarks

If the hook function (pointed to by the lpfnPrintHook or lpfnSetupHook member of the PRINTDLG structure) processes the WM_CTLCOLORDLG message, the hook function must return a handle for the brush that should be used to paint the control background.

An application can use the DC returned by PrintDlg as follows:

•	The connection is established. In other words, the RAS connection state is RASCS_Connected.

•	The connection fails. In other words, dwError is nonzero.

•	RasHangUp is called on the connection.

See Also

CommDlgExtendedError, CreateDC, DOCINFO, PRINTDLG, StartDoc, WM_CTLCOLORDLG


PrinterMessageBox

The PrinterMessageBox function displays a message box that lets an application that is printing notify the user of a printing job error. If the owner of the job is logged on remotely, the function sends a net popup to the owner. If the user selects Cancel in the message box, the function cancels the print job; otherwise, the function clears the job error status, and the system tries to print the job again.

HPRINTER PrinterMessageBox (

HANDLE  hPrinter,	// handle of printer
DWORD  dwError,	// error identifier
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
);
Parameters

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

Return Value

If PrinterMessageBox sends a net popup, the return value is IDOK. Otherwise, the function returns the value returned by the message box the function displays. Two typical return values are the following:

Value	Meaning
IDCANCEL	Cancel button was selected.
IDRETRY	Retry button was selected.
For a more complete list of message box return values, see MessageBox.

See Also

MessageBox


PrinterProperties

The PrinterProperties function displays a printer-properties dialog box for the specified printer.

BOOL PrinterProperties(

hwnd  hwnd,	// handle of parent window
HANDLE  hPrinter	// handle of printer object
);
Parameters

hwnd

Identifies the parent window of the dialog box.

hPrinter

Identifies a printer object.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

OpenPrinter


PrivilegeCheck

The PrivilegeCheck function tests the security context represented by a specific access token to discover whether it contains the specified privileges. This function is typically called by a server application to check the privileges of a client's access token.

BOOL PrivilegeCheck(

HANDLE  hClientToken,	// handle of client's access token
PPRIVILEGE_SET  pps,	// address of privileges
LPBOOL  lpfResult	// address of flag for result
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

AccessCheck, AccessCheckAndAuditAlarm, AreAllAccessesGranted, AreAnyAccessesGranted, LookupPrivilegeDisplayName, LookupPrivilegeName, LookupPrivilegeValue, LUID_AND_ATTRIBUTES, ObjectPrivilegeAuditAlarm, PRIVILEGE_SET, PrivilegedServiceAuditAlarm


PrivilegedServiceAuditAlarm

The PrivilegedServiceAuditAlarm function generates audit messages when an attempt is made to perform privileged system service operations. Alarms are not supported in the current version of Windows NT.

BOOL PrivilegedServiceAuditAlarm(

LPCTSTR  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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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


ProfClear

The ProfClear function is not implemented in the Win32 API.


ProfFinish

The ProfFinish function is not implemented in the Win32 API.


ProfFlush

The ProfFlush function is not implemented in the Win32 API.


ProfInsChk

The ProfInsChk function is not implemented in the Win32 API.


ProfSampRate

The ProfSampRate function is not implemented in the Win32 API.


ProfSetup

The ProfSetup function is not implemented in the Win32 API.


ProfStart

The ProfStart function is not implemented in the Win32 API.


ProfStop

The ProfStop function is not implemented in the Win32 API.


PropEnumProc

A PropEnumProc function is an application-defined callback function that receives property entries from a window's property list. A PropEnumProc function is called as a result of a call to the EnumProps function. A value of type PROPENUMPROC is a pointer to a PropEnumProc function.

BOOL CALLBACK PropEnumProc(

HWND  hwnd,	// handle to window whose property list is being enumerated
LPCTSTR  lpszString,	// string component of property
HANDLE  hData	// data handle component of property
);
Parameters

hwnd

Handle to the window whose property list is being enumerated.

lpszString

Pointer to a null-terminated string. This string is the string component of a property list entry. This is the string that was specified, along with a data handle, when the property was added to the window's property list via a call to the SetProp function.

hData

Handle to data. This handle is the data component of a property list entry.

Return Value

The callback function should return TRUE to continue the property list enumeration.

The callback function should return FALSE to stop the property list enumeration.

Remarks

The following restrictions apply to this callback function:

•	The callback function must not yield control or do anything that might yield control to other tasks.

•	The callback function can call the RemoveProp function. However, RemoveProp can remove only the property passed to the callback function through the callback function's parameters.

•	The callback function should not attempt to add properties.

PropEnumProc is a placeholder for the application-defined function name.

See Also

EnumProps, EnumPropsEx, PropEnumProcEx, RemoveProp, SetProp


PropEnumProcEx

A PropEnumProcEx function is an application-defined callback function that receives property entries from a window's property list. A PropEnumProcEx function is called as a result of a call to the EnumPropsEx function. A value of type PROPENUMPROCEX is a pointer to a PropEnumProcEx function.

BOOL CALLBACK PropEnumProcEx(

HWND  hwnd,	// handle of window with property
LPCTSTR  lpszString,	// string component of property
HANDLE  hData,	// data handle component of property
DWORD  dwData	// application-defined data
);
Parameters

hwnd

Handle to the window whose property list is being enumerated.

lpszString

Pointer to a null-terminated string. This string is the string component of a property list entry. This is the string that was specified, along with a data handle, when the property was added to the window's property list via a call to the SetProp function.

hData

Handle to data. This handle is the data component of a property list entry.

dwData

Application-defined data. This is the value that was specified as the lParam parameter of the call to EnumPropsEx that initiated the enumeration.

Return Value

The callback function should return TRUE to continue the property list enumeration.

The callback function should return FALSE to stop the property list enumeration.

Remarks

The following restrictions apply to this callback function:

•	The callback function must not yield control or do anything that might yield control to other tasks.

•	The callback function can call the RemoveProp function. However, RemoveProp can remove only the property passed to the callback function through the callback function's parameters.

•	The callback function should not attempt to add properties.

PropEnumProcEx is a placeholder for the application-defined function name.

See Also

EnumProps, EnumPropsEx, PropEnumProc, RemoveProp, SetProp


PropertySheet  (preliminaryWindows NT)
PropertySheet  (preliminary−Windows NT)

The PropertySheet function creates a property sheet and adds the pages defined in the specified property sheet header structure.

int PropertySheet(

LPCPROPSHEETHEADER  lppsph
);
Parameters

lppsph

Pointer to a PROPSHEETHEADER structure that defines the frame and pages of a property sheet.

Return Value

Returns a positive value if successful or − 1 otherwise. The following return values have a special meaning:

Value	Meaning
ID_PSREBOOTSYSTEM	A page sent the PSM_REBOOTSYSTEM message to the property sheet. The computer must be restarted for the user's changes to take effect.
ID_PSRESTARTWINDOWS	A page sent the PSM_RESTARTWINDOWS message to the property sheet. Windows must be restarted for the user's changes to take effect.
See Also

PROPSHEETHEADER, PSM_REBOOTSYSTEM, PSM_RESTARTWINDOWS


PropSheetPageProc  (preliminaryWindows NT)
PropSheetPageProc  (preliminary−Windows NT)

The PropSheetPageProc function specifies an application-defined callback function that a property sheet calls when a page is created and when it is about to be destroyed. An application can use this function to perform initialization and cleanup operations for the page.

UINT CALLBACK PropSheetPageProc(

HWND  hwnd,
UINT  uMsg,
LPPROPSHEETPAGE  ppsp
);
Parameters

hwnd

Reserved; must be NULL.

uMsg

Action flag. This parameter can be one of the following values:

Value	Meaning
PSPCB_CREATE	A page is being created. Return nonzero to allow the page to be created or zero to prevent it.
PSPCB_RELEASE	A page is being destroyed. The return value is ignored.
ppsp

Pointer to a PROPSHEETPAGE structure that defines the page being created or destroyed.

Return Value

The return value depends on the value of uMsg.

Remarks

An application must specify the address of this callback function in the pfnCallback member of a PROPSHEETPAGE structure before specifying the address of the structure in a call to the CreatePropertySheetPage function.

See Also

CreatePropertySheetPage, PROPSHEETPAGE


PropSheetProc  (preliminaryWindows NT)
PropSheetProc  (preliminary−Windows NT)

The PropSheetProc function specifies an application-defined callback function that the system calls when the property sheet is being initialized.

VOID CALLBACK PropSheetProc(

HWND  hwndDlg,
UINT  uMsg,
LPARAM  lParam
);
Parameters

hwndDlg

Handle to the property sheet dialog box.

uMsg

Action flag. Currently, only the PSCB_INITIALIZED value is defined, which indicates that the property sheet is being initialized.

lParam

Always zero.

Return Value

No return value.

Remarks

An application must specify the address of this callback function in the pfnCallback member of a PROPSHEETHEADER structure before specifying the address of the structure in a call to the PropertySheet function.

See Also

PropertySheet, PROPSHEETHEADER


PtInRect

The PtInRect function determines whether the specified point lies within the specified rectangle. A point is within a rectangle if it lies on the left or top side or is within all four sides. A point on the right or bottom side is considered outside the rectangle.

BOOL PtInRect(

CONST RECT  *lprc,	// address of structure with rectangle
POINT  pt	// structure with point
);
Parameters

lprc

Points to a RECT structure that contains the specified rectangle.

pt

Specifies a POINT structure that contains the specified point.

Return Value

If the specified point lies within the rectangle, the return value is TRUE.

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

See Also

EqualRect, IsRectEmpty, POINT, RECT


PtInRegion

The PtInRegion function determines whether the specified point is inside the specified region.

BOOL PtInRegion(

HRGN  hrgn,	// handle of region
int  X,	// x-coordinate of point
int  Y	// y-coordinate of point
);
Parameters

hrgn

Identifies the region to be examined.

X

Specifies the x-coordinate of the point.

Y

Specifies the y-coordinate of the point.

Return Value

If the specified point is in the region, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

RectInRegion


PtVisible

The PtVisible function indicates whether the specified point is within the clipping region of a device context.

BOOL PtVisible(

HDC  hdc,	// handle of device context
int  X,	// x-coordinate of point
int  Y	// y-coordinate of point
);
Parameters

hdc

Identifies the device context.

X

Specifies the logical x-coordinate of the point.

Y

Specifies the logical y-coordinate of the point.

Return Value

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


PulseEvent

The PulseEvent function provides a single operation that sets (to signaled) the state of the specified event object and then resets it (to nonsignaled) after releasing the appropriate number of waiting threads.

BOOL PulseEvent(

HANDLE  hEvent	// handle of event object
);
Parameters

hEvent

Identifies the event object. The CreateEvent or OpenEvent function returns this handle, which must have EVENT_MODIFY_STATE access.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

For 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

The PurgeComm function can discard all characters from the output or input buffer of a specified communications resource. It can also terminate pending read or write operations on the resource.

BOOL PurgeComm(

HANDLE  hCommDev,	// handle of communications resource
DWORD  fdwAction	// action to perform
);
Parameters

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	Terminates all outstanding write operations and returns immediately, even if the write operations have not been completed.
PURGE_RXABORT	Terminates all outstanding read operations and returns immediately, even if the read operations have not been completed.
PURGE_TXCLEAR	Clears the output buffer (if the device driver has one).
PURGE_RXCLEAR	Clears the input buffer (if the device driver has one).
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If a thread uses PurgeComm to flush an output buffer, the deleted characters are not transmitted. To empty the output buffer while ensuring that the contents are transmitted, call the FlushFileBuffers function (a synchronous operation). Note, however, that FlushFileBuffers is subject to flow control but not to write time-outs, and it will not return until all pending write operations have been transmitted.

See Also

CreateFile


QueryDosDevice

The QueryDosDevice function lets an application obtain information about MS-DOS device names. The function can obtain the current mapping for a particular MS-DOS device name. The function can also obtain a list of all existing MS-DOS device names.

MS-DOS device names are stored as symbolic links in the Windows NT object name space. The code that converts an MS-DOS path into a corresponding Windows NT path uses these symbolic links to map MS-DOS devices and drive letters. The QueryDosDevice function provides a mechanism whereby a Win32-based application can query the names of the symbolic links used to implement the MS-DOS device namespace as well as the value of each specific symbolic link.

DWORD QueryDosDevice(

LPCTSTR  lpDeviceName,	// address of MS-DOS device name string
LPTSTR  lpTargetPath,	// address of buffer for storing query results
DWORD  ucchMax	// maximum storage capacity of buffer
);
Parameters

lpDeviceName

Pointer to an MS-DOS device name string specifying the target of the query.

This parameter can be NULL. In that case, the QueryDosDevice function will store a list of all existing MS-DOS device names into the buffer pointed to by lpTargetPath.

lpTargetPath

Pointer to a buffer that will receive the result of the query. The function fills this buffer with one or more null-terminated strings. The final null-terminated string is followed by an additional NULL.

If lpDeviceName is non-NULL, the function obtains information about the particular MS-DOS device specified by lpDeviceName. The first null-terminated string stored into the buffer is the current mapping for the device. The other null-terminated strings represent undeleted prior mappings for the device.

If lpDeviceName is NULL, the function obtains a list of all existing MS-DOS device names. Each null-terminated string stored into the buffer is the name of an existing MS-DOS device.

ucchMax

Specifies the maximum number of characters that can be stored into the buffer pointed to by lpTargetPath.

Return Value

If the function succeeds, the return value is the number of characters stored into the buffer pointed to by lpTargetPath.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The DefineDosDevice function provides a means whereby a Win32-based application can create and modify the symbolic links used to implement the MS-DOS device namespace.

MS-DOS device names are global. Once defined, an MS-DOS device name remains visible to all processes until either it is explicity removed or the system reboots.

See Also

DefineDosDevice


QueryPerformanceCounter

The QueryPerformanceCounter function retrieves the current value of the high-resolution performance counter, if one exists.

BOOL QueryPerformanceCounter(

LARGE_INTEGER  *lpliPerformanceCount	// address of current counter value
);
Parameters

lpliPerformanceCount

Points to a variable that the function sets, in counts, to the current performance-counter value. If the installed hardware does not support a high-resolution performance counter, this parameter can be to zero.

Return Value

If the installed hardware supports a high-resolution performance counter, the return value is TRUE.

If the installed hardware does not support a high-resolution performance counter, the return value is FALSE.

See Also

QueryPerformanceFrequency


QueryPerformanceFrequency

The QueryPerformanceFrequency function retrieves the frequency of the high-resolution performance counter, if one exists.

BOOL QueryPerformanceFrequency(

LARGE_INTEGER  *lpliPerformanceFreq	// address of current frequency
);
Parameters

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, this parameter can be to zero.

Return Value

If the installed hardware supports a high-resolution performance counter, the return value is TRUE.

If the installed hardware does not support a high-resolution performance counter, the return value is FALSE. To get extended error information, call GetLastError.

See Also

QueryPerformanceCounter


QueryServiceConfig

The QueryServiceConfig function retrieves the configuration parameters of the specified service.

BOOL QueryServiceConfig(

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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

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

The QueryServiceConfig function returns the service configuration information kept in the registry for a particular service. This configuration information was first set via the CreateService function, and may have been updated via the ChangeServiceConfig function. If the service was running when the configuration information was last changed, the information returned with the QueryServiceConfig will not reflect the true configuration of the service that is running. Instead, it will reflect the configuration of the service when it is run next. Upon stopping the service, the service control manager database will be updated with the configuration that is stored in the registry. The DisplayName key is an exception to this. When the DisplayName key is changed, it takes effect immediately regardless of whether the service is running.

The 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, QUERY_SERVICE_CONFIG, QueryServiceObjectSecurity, QueryServiceStatus


QueryServiceLockStatus

The QueryServiceLockStatus function retrieves the lock status of the specified service control manager database.

BOOL QueryServiceLockStatus(

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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

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

The QueryServiceLockStatus function returns a QUERY_SERVICE_LOCK_STATUS structure that indicates whether the specified database is locked. If the database is locked, the structure provides the account name of the user that holds the lock and the length of time that the lock has been held.

A process calls the LockServiceDatabase function to lock a service control manager database and the UnlockServiceDatabase function to release the lock.

The 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, QUERY_SERVICE_LOCK_STATUS, UnlockServiceDatabase


QueryServiceObjectSecurity

The QueryServiceObjectSecurity function retrieves a copy of the security descriptor protecting a service object.

BOOL QueryServiceObjectSecurity(

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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

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

The initial security descriptor of a service object is created by the service control manager, based on the security descriptor of the process that called the CreateService function to create the service. The security descriptor can be changed by calling the SetServiceObjectSecurity function.

See Also

CreateService, OpenService, SECURITY_DESCRIPTOR, SetServiceObjectSecurity


QueryServiceStatus

The QueryServiceStatus function retrieves the current status of the specified service.

BOOL QueryServiceStatus(

SC_HANDLE  schService,	// handle of service
LPSERVICE_STATUS  lpssServiceStatus	// address of service status structure
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The specified handle was not opened with SERVICE_QUERY_STATUS access.
ERROR_INVALID_HANDLE	The specified handle is invalid.
Remarks

The QueryServiceStatus function returns the most recent service status information reported to the service control manager. The service may have just changed its status and may not have updated the service control manager yet. Applications can find out the absolutely latest service status by interrogating the service directly by using the ControlService function with the SERVICE_CONTROL_INTERROGATE control code.

See Also

ControlService, CreateService, OpenService, SERVICE_STATUS, SetServiceStatus


RaiseException

The RaiseException function raises an exception in the calling thread.

VOID RaiseException(

DWORD  dwExceptionCode,	// exception code
DWORD  dwExceptionFlags,	// continuable exception flag
DWORD  cArguments,	// number of arguments in array
CONST DWORD *  lpArguments	// address of array of arguments
);
Parameters

dwExceptionCode

Specifies the application-defined exception code of the exception being raised. The filter expression and exception-handler block of an exception handler can use the GetExceptionCode function to retrieve this value.

Note that the system will clear bit 28 of dwExceptionCode. This bit is a reserved exception bit, used by the system for its own purposes. For example, after calling the RaiseException function with a dwExceptionCode value of 0xEFFFFFFF Windows displays a message indicating that the exception number is 0xEFFFFFFF.

dwExceptionFlags

Specifies the exception flags. This can be either zero to indicate a continuable exception, or EXCEPTION_NONCONTINUABLE to indicate a noncontinuable exception. Any attempt to continue execution after a noncontinuable exception causes the EXCEPTION_NONCONTINUABLE_EXCEPTION exception.

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.

Return Value

This function does not return a value.

Remarks

The RaiseException function enables a process to use structured exception handling to handle private, software-generated, application-defined exceptions.

Raising an exception causes the exception dispatcher to go through the following search for an exception handler:

1.	The system first attempts to notify the process's debugger, if any.

2.	If the process is not being debugged, or if the associated debugger does not handle the exception, the system attempts to locate a frame-based exception handler by searching the stack frames of the thread in which the exception occurred. The system searches the current stack frame first, then proceeds backward through preceding stack frames.

3.	If no frame-based handler can be found, or no frame-based handler handles the exception, the system makes a second attempt to notify the process's debugger.

4.	If the process is not being debugged, or if the associated debugger does not handle the exception, the system provides default handling based on the exception type. For most exceptions, the default action is to call the ExitProcess function.

The values specified in the dwExceptionCode, dwExceptionFlags, 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

ExitProcess, GetExceptionCode, GetExceptionInformation, WaitForDebugEvent


RasCreatePhonebookEntry

The RasCreatePhonebookEntry function creates a new phonebook entry. The function displays a dialog box for the user to enter the information about the phonebook entry.

DWORD RasCreatePhonebookEntry(

HWND  hwnd,	// handle to parent window for dialog box
LPTSTR  lpszPhonebook	// pointer to full path and filename of phonebook file
);
Parameters

hwnd

Handle of the parent window for the dialog box.

lpszPhonebook

Points to a null-terminated string that specifies the full path and filename of the phonebook file. Currently, this parameter is ignored. RasCreatePhonebookEntry always uses the default phonebook file, RASPHONE.PBK.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes:

Value	Description
ERROR_CANNOT_OPEN_PHONEBOOK	The phonebook is corrupted or missing components.
See Also

RasEditPhonebookEntry, RasGetEntryDialParams, RasSetEntryDialParams


RasDial

The RasDial function establishes a Remote Access Service (RAS) connection between a RAS client and a RAS server. The connection data includes callback and user authentication information.

DWORD RasDial(

LPRASDIALEXTENSIONS  lpRasDialExtensions,	// pointer to function extensions data
LPTSTR  lpszPhonebook,	// pointer to full path and filename of phonebook file
LPRASDIALPARAMS  lpRasDialParams,	// pointer to calling parameters data
DWORD  dwNotifierType,	// specifies type of RasDial event handler
LPVOID  lpvNotifier,	// specifies a handler for RasDial events
LPHRASCONN  lphRasConn	// pointer to variable to receive connection handle
);
Parameters

lpRasDialExtensions

Windows NT

Points to a RASDIALEXTENSIONS structure that specifies a set of RasDial extended features to enable. If you do not need to enable any of the extensions, set this parameter to NULL.

Windows 95

This parameter is ignored. On Windows 95, RasDial always uses the default behaviors for the RASDIALEXTENSIONS options.

lpszPhonebook

Windows NT

Points to a string that specifies the full path and filename of the phonebook file. This parameter can be NULL, and typically is; in that case, RasDial uses the default phonebook file, RASPHONE.PBK.

Windows 95

This parameter is ignored. On Windows 95, RasDial always uses the default phonebook file, RASPHONE.PBK.

lpRasDialParams

Points to a RASDIALPARAMS structure that specifies calling parameters for the RAS connection.

The caller must set the RASDIALPARAMS structure's dwSize member to the sizeof(RASDIALPARAMS) to identify the version of the structure being passed.

dwNotifierType

Specifies the nature of the lpvNotifier parameter. You must set dwNotifierType to one of the following values:

Value	Meaning
0xFFFFFFFF	The lpvNotifier parameter is a handle to a window to receive progress notification messages. In a progress notification message, wParam is the equivalent of the rasconnstate parameter of RasDialFunc and RasDialFunc1, and lParam is the equivalent of the dwError parameter of RasDialFunc and RasDialFunc1.  The progress notification message uses a system registered message code. You can obtain the value of this message code as follows:  {UINT unMsg =    RegisterWindowMessageA( RASDIALEVENT );  if (unMsg == 0)        unMsg = WM_RASDIALEVENT;     }
0	The lpvNotifier parameter points to a RasDialFunc callback function. See RasDialFunc for a full description of this type of callback function.
1	The lpvNotifier parameter points to a RasDialFunc1 callback function. See RasDialFunc1 for a full description of this type of callback function.
lpvNotifier

Specifies a window or a callback function to handle RasDial events. The dwNotifierType parameter specifies the nature of lpvNotifier. Please refer to its description preceding for further detail.

If this parameter is not NULL, RasDial sends the window a message, or calls the callback function, for each RasDial event. Additionally, the RasDial call operates asynchronously: RasDial returns immediately, before the connection is established, and communicates its progress via the window or callback function.

If lpvNotifier is NULL, the RasDial call operates synchronously: RasDial does not return until the connection attempt has completed successfully or failed.

If lpvNotifier is not NULL, notifications to the window or callback function can occur at any time after the initial call to RasDial. Notifications end when one of the following events occurs:

•	The connection is established. In other words, the RAS connection state is RASCS_Connected.

•	The connection fails. In other words, dwError is nonzero.

•	RasHangUp is called on the connection.

The callback notifications are made in the context of a thread captured during the initial call to RasDial.

lphRasConn

Points to a variable of type HRASCONN. You must set the HRASCONN variable to NULL before calling RasDial. If RasDial succeeds, it stores a handle to the RAS connection into *lphRasConn.

Return Value

If the function succeeds, the immediate return value is zero. In addition, the function stores a handle to the RAS connection into the variable pointed to by lphRasConn.

If the function fails, the immediate return value is a nonzero error value, either from the set listed in the RAS header file or ERROR_NOT_ENOUGH_MEMORY.

Remarks

Errors that occur after the immediate return can be detected by RasGetConnectStatus. Data is available until an application calls RasHangUp to hang up the connection.

An application must eventually call RasHangUp whenever a non-NULL connection handle is stored into *lphRasConn. This applies even if RasDial returns a nonzero (error) value.

An application can safely call RasHangUp from a RasDial notifier callback function. If this is done, however, the hangup does not occur until the routine returns.

If the structure pointed to by lpRasDialExtensions enables RDEOPT_PausedStates, the RasDial function pauses whenever it enters a state in which the RASCS_PAUSED bit is set to one. To restart RasDial from such a paused state, call RasDial again, passing the connection handle returned from the original RasDial call in *lphRasConn. The same notifier used in the original RasDial call must be used when restarting from a paused state.

To specify that RasDial should enter a RASCS_CallbackSetByCaller state, set lpRasDialParams-->szCallbackNumber to "*" on the initial call to RasDial. When your notification handler is called with this state, you can set the the callback number to a number supplied by the user.

See Also

RasDialFunc, RasDialFunc1, RasGetConnectStatus, RasHangUp, RASDIALEXTENSIONS, RASDIALPARAMS, WM_RASDIALEVENT


RasDialFunc

The RasDialFunc function is an application-defined or library-defined callback function that the RasDial function calls when a change of state occurs during a Remote Access Service (RAS) connection process.

VOID RasDialFunc(

UINT  unMsg,	// type of event that has occurred
RASCONNSTATE  rasconnstate,	// connection state about to be entered
DWORD  dwError	// error that may have occurred
);
Parameters

unMsg

Specifies the type of event that has occurred. Currently, the only event defined is WM_RASDIALEVENT.

rasconnstate

Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.

dwError

Indicates the error that has occurred, or zero if no error has occurred.

RasDial calls RasDialFunc with dwError set to zero upon entry to each connection state. If an error occurs within a state, RasDialFunc is called again for the state, this time with a nonzero dwError value.

Remarks

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 time-out periods measured in seconds rather than milliseconds; a less-than-prompt return from a RasDialFunc function is generally not a problem. The prompt return requirement also does not apply when dwError is nonzero, indicating that an error has occurred. It is safe, for example, to put up an error dialog box and wait for user input.

RasDial should not be called from within a RasDialFunc callback function. The other remote access functions (RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp) can be called from within the callback function. For example, calling RasGetConnectStatus from within a callback function would be useful for determining the name and type of the connecting device.

Note that, for convenience, RasHangUp can be called from within a RasDialFunc callback function. However, much of the hang-up processing occurs after the RasDialFunc callback function has returned.

RasDialFunc is a placeholder for the application-defined or library-defined function name.

See Also

RASCONNSTATE, RasDial, RasDialFunc1, RasEnumConnections, RasEnumEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp


RasDialFunc1

A RasDialFunc1 function is an application-defined or library-defined callback function that the RasDial function calls when a change of state occurs during a remote access connection process. A RasDialFunc1 function is comparable to a RasDialFunc function, but is enhanced by the addition of two parameters: a handle to the Remote Access Server (RAS) connection, and an extended error code.

VOID RasDialFunc1(

HRASCONN  hrasconn,	// handle to RAS connection
UINT  unMsg,	// type of event that has occurred
RASCONNSTATE  rascs,	// connection state about to be entered
DWORD  dwError	// error that may have occurred
DWORD  dwExtendedError	// extended error information for some errors
);
Parameters

hrasconn

Provides a handle to the RAS connection, as returned by RasDial.

unMsg

Specifies the type of event that has occurred. Currently, the only event defined is WM_RASDIALEVENT.

rascs

Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.

dwError

Specifies the error that has occurred. If no error has occurred, dwError is zero.

RasDial calls a RasDialFunc1 with dwError set to zero upon entry to each connection state. If an error occurs within a state, RasDial calls RasDialFunc1 again for the state, this time with a nonzero dwError value.

In some error cases, the dwExtendedError parameter contains extended error information.

dwExtendedError

Specifies extended error information for certain nonzero values of dwError. For all other values of dwError, dwExtendedError is zero.

The contents of dwExtendedError are defined for values of dwError as follows:

dwError	dwExtendedError
ERROR_SERVER_NOT_RESPONDING	Specifies the NetBIOS error that occurred.
ERROR_NETBIOS_ERROR	Specifies the NetBIOS error that occurred.
ERROR_AUTH_INTERNAL	Specifies an internal diagnostics code.
ERROR_CANNOT_GET_LANA	Specifies a routing error code, which is a RAS error.
Remarks

The RAS connection state computer is suspended during the call to a RasDialFunc1 callback function. For that reason, a RasDialFunc1 callback function should generally return as quickly as possible. There are two exceptions to that rule. Asynchronous (slow) devices such as modems often have time-out periods measured in seconds rather than milliseconds; a less-than-prompt return from a RasDialFunc1 function is generally not a problem. The prompt return requirement also does not apply when dwError is nonzero, indicating that an error has occurred. It is safe, for example, to put up an error dialog box and wait for user input.

RasDial should not be called from within a RasDialFunc1 callback function. The other remote access functions (RasGetConnectStatus, RasEnumEntries, RasEnumConnections, RasGetErrorString, and RasHangUp) can be called from within the callback function. For example, calling RasGetConnectStatus from within a callback function would be useful for determining the name and type of the connecting device.

Note that, for convenience, RasHangUp can be called from within a RasDialFunc1 callback function. However, much of the hang-up processing occurs after the RasDialFunc1 callback function has returned.

RasDialFunc1 is a placeholder for the application-defined or library-defined function name.

See Also

RasDial, RasDialFunc, RASCONNSTATE, RasEnumConnections, RasEnumEntries, RasGetConnectStatus, RasGetErrorString, RasHangUp


RasEditPhonebookEntry

The RasEditPhonebookEntry function edits an existing phonebook entry. The function displays a dialog box for the user to modify the existing information.

DWORD RasEditPhonebookEntry(

HWND  hwnd,	// handle to parent window for dialog box
LPTSTR  lpszPhonebook,	// pointer to full path and filename of phonebook file
LPTSTR  lpszEntryName	// pointer to phonebook entry name
);
Parameters

hwnd

Handle of the parent window for the dialog box.

lpszPhonebook

Points to a null-terminated string that specifies the full path and filename of the phonebook file. Currently, this parameter is ignored. RasEditPhonebookEntry always uses the default phonebook file, RASPHONE.PBK.

lpszEntryName

Points to a null-terminated string that specifies the name of an existing entry in the phonebook file.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes:

Value	Description
ERROR_BUFFER_INVALID	The phonebook entry buffer is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK	The phonebook is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	The phonebook entry does not exist.
See Also

RasCreatePhonebookEntry, RasGetEntryDialParams, RasSetEntryDialParams


RasEnumConnections

The RasEnumConnections function lists all active Remote Access Service (RAS) connections. It returns each connection's handle and phonebook entry name.

DWORD RasEnumConnections(

LPRASCONN  lprasconn,	// buffer to receive connections data
LPDWORD  lpcb,	// size in bytes of buffer
LPDWORD  lpcConnections	// number of connections written to buffer
);
Parameters

lprasconn

Points to a buffer that receives an array of RASCONN structures, one for each RAS connection. Before calling the function, an application must set the dwSize member of the first RASCONN structure in the buffer to sizeof(RASCONN) in order to identify the version of the structure being passed.

lpcb

Points to a variable that contains the size, in bytes, of the buffer specified by lprasconn. On return, the function sets this variable to the number of bytes required to enumerate the RAS connections.

lpcConnections

Points to a variable that the function sets to the number of RASCONN structures written to the buffer specified by lprasconn.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file or one of ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

Remarks

If a connection was made without specifying a phonebook entry name, the information returned for that connection will give the connection phone number preceded by ".".

See Also

RASCONN, RasEnumEntries, RasGetConnectStatus


RasEnumEntries

The RasEnumEntries function lists all entry names in a remote access phonebook.

DWORD RasEnumEntries (

LPTSTR  reserved,	// reserved, must be NULL
LPTSTR  lpszPhonebook,	// pointer to full path and filename of phonebook file
LPRASENTRYNAME  lprasentryname,	// buffer to receive phonebook entries
LPDWORD  lpcb,	// size in bytes of buffer
LPDWORD  lpcEntries	// number of entries written to buffer
);
Parameters

reserved

Reserved; must be NULL.

lpszPhonebook

Windows NT

Points to a string that specifies the full path and filename of the phonebook file. This parameter can be NULL, and typically is; in that case, RasEnumEntries uses the default phonebook file, RASPHONE.PBK.

Windows 95

This parameter is ignored. On Windows 95, RasEnumEntries always uses the default phonebook file, RASPHONE.PBK.

lprasentryname

Points to a buffer that receives an array of RASENTRYNAME structures, one for each phonebook entry. Before calling the function, an application must set the dwSize member of the first RASENTRYNAME structure in the buffer to sizeof(RASENTRYNAME) in order to identify the version of the structure being passed.

lpcb

Points to a variable that contains the size, in bytes, of the buffer specified by lprasentryname. On return, the function sets this variable to the number of bytes required to successfully complete the call.

lpcEntries

Points to a variable that the function, if successful, sets to the number of phonebook entries written to the buffer specified by lprasentryname.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file or one of ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

See Also

RASENTRYNAME, RasEnumConnections


RasGetConnectStatus

The RasGetConnectStatus function retrieves information on the current status of the specified remote access connection. An application can use this call to determine when an asynchronous RasDial call has completed.

DWORD RasGetConnectStatus(

HRASCONN  hrasconn,	// handle to RAS connection of interest
LPRASCONNSTATUS  lprasconnstatus	// buffer to receive status data
);
Parameters

hrasconn

Identifies the remote access connection for which to retrieve the status. This handle must have been obtained from RasDial or RasEnumConnections.

lprasconnstatus

Points to a RASCONNSTATUS structure that the function fills with status information. Before calling the function, an application must set the dwSize member of the structure to sizeof(RASCONNSTATUS) in order to identify the version of the structure being passed.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file or one of ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

See Also

RASCONNSTATUS, RasDial, RasEnumConnections


RasGetEntryDialParams

The RasGetEntryDialParams function retrieves the connection information saved by the last successful call to the RasDial or RasSetEntryDialParams function for a specified phonebook entry.

DWORD RasGetEntryDialParams(

LPTSTR  lpszPhonebook,	// pointer to full path and filename of phonebook file
LPRASDIALPARAMS  lprasdialparams,	// pointer to structure that receives the connection parameters
LPBOOL  lpfPassword	// indicates whether user's password was retrieved
);
Parameters

lpszPhonebook

Points to a null-terminated string that specifies the full path and filename of the phonebook file. Currently, this parameter is ignored. RasGetEntryDialParams always uses the default phonebook file, RASPHONE.PBK.

lprasdialparams

Points to a RASDIALPARAMS structure that receives the connection parameters associated with the phonebook entry specified by the szEntryName member. On entry, the dwSize member must specify the size of the RASDIALPARAMS structure, and the szEntryName member must specify a valid phonebook entry.

lpfPassword

Points to a flag that indicates whether the function retrieved the password associated with the user name for the phonebook entry. The function sets this flag to TRUE if the szPassword member of the lprasdialparams structure contains the user's password.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes:

Value	Description
ERROR_BUFFER_INVALID	The lprasdialparams or lpfPassword pointer is invalid, or the lprasdialparams buffer is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK	The phonebook is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	The phonebook entry does not exist.
See Also

RasDial, RASDIALPARAMS, RasCreatePhonebookEntry, RasEditPhonebookEntry, RasSetEntryDialParams


RasGetErrorString

The RasGetErrorString function obtains an error message string for a specified Remote Access Service (RAS) error value.

DWORD RasGetErrorString (

UINT  uErrorValue,	// error to get string for
LPTSTR  lpszErrorString,	// buffer to hold error string
DWORD  cBufSize	// sizeof buffer
);
Parameters

uErrorValue

Specifies the error value of interest. These are values returned by one of the RAS functions: those listed in the RAS header file.

lpszErrorString

Points to a buffer that the function will write the error string to. This parameter must not be NULL.

cBufSize

Specifies the size, in characters, of the buffer pointed to by lpszErrorString.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value. This value is ERROR_INVALID_PARAMETER or the GetLastError value returned from the functions GlobalAlloc or LoadString. The function does not set a thread's last error information; that is, there is no GetLastError information set by the RasGetErrorString function.

Remarks

There is no way to determine in advance the exact size in characters of an error message, and thus the size of buffer required. Error messages will generally be 80 characters or fewer in size; a buffer size of 256 characters will always be adequate. A buffer of insufficient size causes the RasGetErrorString function to fail, returning ERROR_INSUFFICIENT_BUFFER. Note that buffer sizes are specified in characters, not bytes; thus, the Unicode version of RasGetErrorString requires a 512 byte buffer to guarantee that every error message will fit.

See Also

GlobalAlloc, LoadString


RasGetProjectionInfo

The RasGetProjectionInfo function obtains information about a remote access projection operation for a specified remote access component protocol.

DWORD RasGetProjectionInfo(

HRASCONN  hrasconn,	// handle that specifies remote access connection of interest
RASPROJECTION  rasprojection,	// specifies type of projection information to obtain
LPVOID  lpprojection,	// points to buffer that receives projection information
LPDWORD  lpcb	// points to variable that specifies buffer size
);
Parameters

hrasconn

Handle to the remote access connection of interest. An application obtains a Remote Access Service (RAS) connection handle from the RasDial or RasEnumConnections function.

rasprojection

A RASPROJECTION enumerated type value that specifies the protocol of interest.

lpprojection

Points to a buffer that will receive the information specified by the rasprojection parameter. The information will be in a structure appropriate to the rasprojection value:

rasprojection value	Data structure
RASP_Amb	RASAMB
RASP_PppNbf	RASPPPNBF
RASP_PppIpx	RASPPPIPX
RASP_PppIp	RASPPPIP
lpcb

Points to a variable that, on entry, specifies the size in bytes of the buffer pointed to by lpprojection. On exit, this variable contains the size of buffer needed to contain the specified projection information.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is an error code. The function may return a nonzero RAS error code, or one of the following error codes:

Value	Meaning
ERROR_BUFFER_TOO_SMALL	The buffer pointed to by lpprojection is not large enough to contain the requested information.
ERROR_INVALID_HANDLE	The hrasconn parameter is not a valid handle.
ERROR_INVALID_PARAMETER	One of the parameters is invalid.
ERROR_INVALID_SIZE	The dwSize member of the structure pointed to by lpprojection specifies an invalid size.
ERROR_PROTOCOL_NOT_CONFIGURED	The control protocol for which information was requested neither succeeded nor failed, because the connection's phonebook entry did not require that an attempt to negotiate the protocol be made. This is a RAS error code.
Remarks

Remote access projection is the process whereby a remote access server and a remote client negotiate network protocol-specific information. A remote access server uses this network protocol-specific information to represent a remote client on the network.

Windows NT: Remote access projection information is not available until the operating system has executed the RasDial RASCS_Projected state on the remote access connection. If RasGetProjectionInfo is called prior to the RASCS_Projected state, it returns ERROR_PROJECTION_NOT_COMPLETE.

Windows 95: Windows 95 Dial-Up Networking does not support the RASCS_Projected state. The projection phase may be done during the RASCS_Authenticate state. If the authentication is successful, the connection operation proceeds to the RASCS_Authenticated state, and projection information is available for successfully configured protocols. If RasGetProjectionInfo is called prior to the RASCS_Authenticated state, it returns ERROR_PROTOCOL_NOT_CONFIGURED.

See Also

RASAMB, RasDial, RasEnumConnections, RASPPPNBF, RASPPPIPX, RASPPPIP, RASPROJECTION


RasHangUp

The RasHangUp function terminates a remote access connection. The connection is specified with a Remote Access Service (RAS) connection handle. The function releases all RASAPI32.DLL resources associated with the handle.

DWORD RasHangUp(

HRASCONN  hrasconn	// handle to the RAS connection to hang up
);
Parameters

hrasconn

Identifies the remote access connection to terminate. This is a handle returned from a previous call to RasDial or RasEnumConnections.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file, or ERROR_INVALID_HANDLE.

Remarks

The connection is terminated even if the RasDial call has not yet been completed.

After this call, the hrasconn handle can no longer be used.

An application should not call RasHangUp and then immediately exit. The connection state machine needs time to properly terminate. If the system prematurely terminates the state machine, the state machine may fail to properly close a port, leaving the port in an inconsistent state. A simple way to avoid this problem is to call Sleep(3000) after returning from RasHangUp; after that pause, the application can exit. A more responsive way to avoid the problem is, after returning from RasHangUp, to call RasGetConnectStatus(hrasconn) and Sleep(0) in a loop until RasGetConnectStatus returns ERROR_INVALID_HANDLE.

See Also

RASCONN, RasDial, RasEnumConnections, RasGetConnectStatus, Sleep


RasSetEntryDialParams

The RasSetEntryDialParams function changes the connection information saved by the last successful call to the RasDial or RasSetEntryDialParams function for a specified phonebook entry.

DWORD RasSetEntryDialParams(

LPTSTR  lpszPhonebook,	// pointer to full path and filename of phonebook file
LPRASDIALPARAMS  lprasdialparams,	// pointer to structure with the new connection parameters
BOOL    fRemovePassword	// indicates whether to remove password from entry's parameters
);
Parameters

lpszPhonebook

Points to a null-terminated string that specifies the full path and filename of the phonebook file. Currently, this parameter is ignored. RasSetEntryDialParams always uses the default phonebook file, RASPHONE.PBK.

lprasdialparams

Points to a RASDIALPARAMS structure containing the connection parameters to be associated with the phonebook entry. RasSetEntryDialParams uses the structure's members as follows:

Member	Description
dwSize	Must specify the sizeof(RASDIALPARAMS) to identify the version of the structure.
szEntryName	Points to a null-terminated string that identifies the phonebook entry to set parameters for.
szPhoneNumber	Not used. Set to NULL.
szCallbackNumber	Points to a null-terminated string containing the callback phone number. If the string is empty, the callback number is not changed.
szUserName	Points to a null-terminated string containing the logon name of the user associated with this entry. If the string is empty, the user name is not changed.
szPassword	Points to a null-terminated string containing the password for the user specified by szUserName. If the szUserName string is empty, the password is not changed.
szDomain	Points to a null-terminated string containing the name of the domain to log on to. If the string is empty, the domain name is not changed.
fRemovePassword

Indicates whether to remove the password string associated with the phonebook entry. If TRUE, the password is removed.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes:

Value	Description
ERROR_BUFFER_INVALID	The address or buffer specified by lprasdialparams is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK	The phonebook is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	The phonebook entry does not exist.
See Also

RASDIALPARAMS, RasCreatePhonebookEntry, RasEditPhonebookEntry, RasGetEntryDialParams


ReadConsole

The ReadConsole function reads character input from the console input buffer and removes it from the buffer.

BOOL ReadConsole(

HANDLE  hConsoleInput,	// handle of a console input buffer
LPVOID  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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

ReadConsole reads keyboard input from a console's input buffer. It behaves like the ReadFile function, except that it can read in either Unicode (wide-character) or ANSI mode. To have applications that maintain a single set of sources compatible with both modes, use ReadConsole rather than ReadFile. Although ReadConsole can only be used with a console input buffer handle, ReadFile can be used with other handles (such as files or pipes). ReadConsole fails if used with a standard handle that has been redirected to be something other than a console handle.

All of the input modes that affect the behavior of ReadFile have the same effect on ReadConsole. To retrieve and set the input modes of a console input buffer, use the GetConsoleMode and SetConsoleMode functions.

If the input buffer contains input events other than keyboard events (such as mouse events or window-resizing events), they are discarded. Those events can only be read by using the ReadConsoleInput function.

See Also

GetConsoleMode, ReadConsoleInput, ReadFile, SetConsoleMode, WriteConsole


ReadConsoleInput

The ReadConsoleInput function reads data from a console input buffer and removes it from the buffer.

BOOL ReadConsoleInput(

HANDLE  hConsoleInput,	// handle of a console input buffer
PINPUT_RECORD  pirBuffer,	// address of the buffer for read data
DWORD  cInRecords,	// number of records to read
LPDWORD  lpcRead	// address of number of records read
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the 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 (for example, 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, INPUT_RECORD, PeekConsoleInput, ReadConsole, ReadFile, WaitForSingleObject, WaitForMultipleObjects, WriteConsoleInput


ReadConsoleOutput

The ReadConsoleOutput function reads character and color attribute data from a rectangular block of character cells in a console screen buffer, and the function writes the data to a rectangular block at a specified location in the destination buffer.

BOOL ReadConsoleOutput(

HANDLE  hConsoleOutput,	// handle of a console screen buffer
PCHAR_INFO  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
);
Parameters

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 that receives the data read from the screen buffer. The X member of the COORD structure is the column, and the Y member is the row.

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 the function is to read. On output, the structure members specify the actual rectangle that the function copied from.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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 be read from the screen buffer. A destination rectangle of the same size is located with its upper-left cell at the coordinates of the 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. If the corresponding cell is outside the boundaries of the destination buffer rectangle (whose dimensions are specified by the coordDestBufferSize parameter), the data is not copied.

Cells in the destination buffer corresponding to coordinates that are not within the boundaries of the screen buffer are left unchanged. In other words, these are the cells for which no screen buffer data is available to be read.

Before ReadConsoleOutput returns, it sets the members of the structure pointed to by the psrctSourceRect parameter to the actual screen buffer rectangle whose cells were copied into the destination buffer. This rectangle reflects the cells in the source rectangle for which there existed a corresponding cell in the destination buffer, because ReadConsoleOutput clips the dimensions of the source rectangle to fit the boundaries of the screen buffer.

If the rectangle specified by 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

CHAR_INFO, COORD, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, SMALL_RECT, WriteConsoleOutput


ReadConsoleOutputAttribute

The ReadConsoleOutputAttribute function copies a specified number of foreground and background color attributes from consecutive cells of a console screen buffer, beginning at a specified location.

BOOL ReadConsoleOutputAttribute(

HANDLE  hConsoleOutput,	// handle of a console screen buffer
LPWORD  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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the number of attributes to be read from extends beyond the end of the specified screen buffer row, attributes are read from the next row. If the number of attributes to be read from extends beyond the end of the screen buffer, attributes up to the end of the screen buffer are read.

Each attribute specifies the foreground (text) and background colors in which that character cell is drawn. The attribute values are some combination of the following values: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces red text on a white background:

FOREGROUND_RED | BACKGROUND_RED | BACKGROUND_GREEN | BACKGROUND_BLUE

See Also

COORD, ReadConsoleOutput, ReadConsoleOutputCharacter, WriteConsoleOutput, WriteConsoleOutputAttribute, WriteConsoleOutputCharacter


ReadConsoleOutputCharacter

The ReadConsoleOutputCharacter function copies a number of characters from consecutive cells of a console screen buffer, beginning at a specified location.

BOOL ReadConsoleOutputCharacter(

HANDLE  hConsoleOutput,	// handle of a console screen buffer
LPTSTR  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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the number of characters to be read from extends beyond the end of the specified screen buffer row, characters are read from the next row. If the number of characters to be read from extends beyond the end of the screen buffer, characters up to the end of the screen buffer are read.

See Also

COORD, ReadConsoleOutput, ReadConsoleOutputAttribute, WriteConsoleOutput, WriteConsoleOutputAttribute, WriteConsoleOutputCharacter


ReadEventLog

The ReadEventLog function reads a whole number of entries from the specified event log. The function can be used to read log entries in forward or reverse chronological order.

BOOL ReadEventLog(

HANDLE  hEventLog,	// handle of event log
DWORD  dwReadFlags,	// specifies how to read log
DWORD  dwRecordOffset,	// number of first record
LPVOID  lpBuffer,	// address of buffer for read data
DWORD  nNumberOfBytesToRead,	// number of bytes to read
DWORD  *pnBytesRead,	// number of bytes read
DWORD  *pnMinNumberOfBytesNeeded	// number of bytes required for next record
);
Parameters

hEventLog

Identifies the event log to read. This handle is returned by the OpenEventLog function.

dwReadFlags

Specifies how the read operation is to proceed. This parameter can be any combination of the following values:

Value	Meaning
EVENTLOG_FORWARDS_READ	The log is read in forward chronological order.
EVENTLOG_BACKWARDS_READ	The log is read in reverse chronological order.
EVENTLOG_SEEK_READ	The read operation proceeds from the record specified by the dwRecordOffset parameter. If this flag is used, dwReadFlags must also specify EVENTLOG_FORWARDS_READ or EVENTLOG_BACKWARDS_READ. If the buffer is large enough, more than one record can be read at the specified seek position; the additional flag indicates the direction for successive read operations.
EVENTLOG_SEQUENTIAL_READ	The read operation proceeds sequentially from the last call to the ReadEventLog function using this handle.
dwRecordOffset

Specifies the log-entry record number at which the read operation should start. This parameter is ignored unless the dwReadFlags parameter includes the EVENTLOG_SEEK_READ flag.

lpBuffer

Points to a buffer for the data read from the event log. This parameter cannot be NULL, even if the nNumberOfBytesToRead parameter is zero.

The buffer will be filled with an EVENTLOGRECORD structure.

nNumberOfBytesToRead

Specifies the size, in bytes, of the buffer. This function will read as many whole log entries as will fit in the buffer; the function will not return partial entries, even if there is room in the buffer.

pnBytesRead

Points to a variable that receives the number of bytes read by the function.

pnMinNumberOfBytesNeeded

Points to a variable that receives the number of bytes required for the next log entry. This count is valid only if ReadEventLog returns zero and GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

When this function returns, the read position in the error log is adjusted by the number of records read. Only a whole number of event log records will be returned.

Note  The configured filename for this source may also be the configured filename for other sources (several sources can exist as subkeys under a single logfile). Therefore, this function may return events that were logged by more than one source.

See Also

ClearEventLog, CloseEventLog, EVENTLOGRECORD, OpenEventLog, ReportEvent


ReadFile

The ReadFile function reads data from a file, starting at the position indicated by the file pointer. After the read operation has been completed, the file pointer is adjusted by the number of bytes actually read, unless the file handle is created with the overlapped attribute. If the file handle is created for overlapped input and output (I/O), the application must adjust the position of the file pointer after the read operation.

BOOL ReadFile(

HANDLE  hFile,	// handle of file to read
LPVOID  lpBuffer,	// address of buffer that receives data
DWORD  nNumberOfBytesToRead,	// number of bytes to read
LPDWORD  lpNumberOfBytesRead,	// address of number of bytes read
LPOVERLAPPED  lpOverlapped	// address of structure for data
);
Parameters

hFile

Identifies the file to be read. The file handle must have been created with GENERIC_READ access to the file.

Windows NT

For asynchronous read operations, this can be any handle opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept functions.

Windows 95

For asynchronous read operations, this can be a communications resource, mailslot, or named pipe handle opened with the FILE_FLAG_OVERLAPPED flag by CreateFile, or a socket handle returned by the socket or accept functions. Windows 95 does not support asynchronous read operations on disk files.

lpBuffer

Points to the buffer that receives the data read from the file.

nNumberOfBytesToRead

Specifies the number of bytes to be read from the file.

lpNumberOfBytesRead

Points to the number of bytes read. ReadFile sets this value to zero before doing any work or error checking. If this parameter is zero when ReadFile returns TRUE on a named pipe, the other end of the message-mode pipe called the WriteFile function with nNumberOfBytesToWrite set to zero.

lpOverlapped

Points to an OVERLAPPED structure. This structure is required if hFile was created with FILE_FLAG_OVERLAPPED.

This parameter should not be NULL if hFile was created with FILE_FLAG_OVERLAPPED. It should point to a valid OVERLAPPED structure. If the file identified by the hFile parameter 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. The function operates synchronously.

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.

Return Value

If the function succeeds, the return value is TRUE. 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 operation.

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

Remarks

If part of the file is locked by another process and the read operation overlaps the locked portion, this function fails.

Applications must not read from nor write to the input buffer that a read operation is using until the read operation completes. A premature access to the input buffer may lead to corruption of the data read into that buffer.

Characters can be read from the console input buffer by using ReadFile with a handle to console input. The console mode determines the exact behavior of the ReadFile function.

If a named pipe is being read in message mode and the next message is longer than the nNumberOfBytesToRead parameter specifies, ReadFile returns FALSE and GetLastError returns ERROR_MORE_DATA. The remainder of the message may be read by a subsequent call to the ReadFile or PeekNamedPipe function.

When reading from a communications device, the behavior of ReadFile is governed by the current communication timeouts as set and retrieved using the SetCommTimeouts and GetCommTimeouts functions. Unpredictable results can occur if you fail to set the timeout values. For more information about communication timeouts, see COMMTIMEOUTS.

If ReadFile attempts to read from a mailslot whose buffer is too small, the function returns FALSE and GetLastError returns ERROR_INSUFFICIENT_BUFFER.

If the anonymous write pipe handle has been closed and ReadFile attempts to read using the corresponding anonymous read pipe handle, the function returns FALSE and GetLastError returns ERROR_BROKEN_PIPE.

The ReadFile function may fail and return ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

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.

The ReadFile code to check for the end-of-file condition (eof) differs for synchronous and asynchronous read operations.

When a synchronous read operation reaches the end of a file, ReadFile returns TRUE and sets *lpNumberOfBytesRead to zero. The following sample code tests for end-of-file for a synchronous read operation:

// attempt a synchronous read operation

bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead, NULL) ;

// check for eof

if (bResult &&  nBytesRead == 0, ) {

// we're at the end of the file

}

An asynchronous read operation can encounter the end of a file during the initiating call to ReadFile, or during subsequent asynchronous operation.

If EOF is detected at ReadFile time for an asynchronous read operation, ReadFile returns FALSE and GetLastError returns ERROR_HANDLE_EOF.

If EOF is detected during subsequent asynchronous operation, the call to GetOverlappedResult to obtain the results of that operation returns FALSE and GetLastError returns ERROR_HANDLE_EOF.

The following sample code illustrates testing for end-of-file for an asynchronous read operation:

// set up overlapped structure fields

// to simplify this sample, we'll eschew an event handle

gOverLapped.Offset     = 0;

gOverLapped.OffsetHigh = 0;

gOverLapped.hEvent     = NULL;

// attempt an asynchronous read operation

bResult = ReadFile(hFile, &inBuffer, nBytesToRead, &nBytesRead,

 &gOverlapped) ;

// if there was a problem, or the async. operation's still pending ...

if (!bResult) {

// deal with the error code

switch (dwError = GetLastError()) {

case ERROR_HANDLE_EOF: {

// we're reached the end of the file

// during the call to ReadFile

// code to handle that

}

case ERROR_IO_PENDING: {

// asynchronous i/o is still in progress

// do something else for a while

GoDoSomethingElse() ;

// check on the results of the asynchronous read

bResult = GetOverlappedResult(hFile, &gOverlapped,

&nBytesRead, FALSE) ;

// if there was a problem ...

if (!bResult) {

// deal with the error code

switch (dwError = GetLastError()) {

case ERROR_HANDLE_EOF: {

// we're reached the end of the file

//during asynchronous operation

}

// deal with other error cases

} // end switch

} // end if

} // end case

// deal with other error cases

} // end switch

} // end if

See Also

CreateFile, GetCommTimeouts, GetOverlappedResult, OVERLAPPED, PeekNamedPipe, ReadFileEx, SetCommTimeouts, WriteFile


ReadFileEx

The ReadFileEx function reads data from a file asynchronously. It is designed solely for asynchronous operation, unlike the ReadFile function, which is designed for both synchronous and asynchronous operation. ReadFileEx lets an application perform other processing during a file read operation.

The ReadFileEx function reports its completion status asynchronously, calling a specified completion routine when reading is completed and the calling thread is in an alertable wait state.

BOOL ReadFileEx(

HANDLE  hFile,	// handle of file to read
LPVOID  lpBuffer,	// address of buffer
DWORD  nNumberOfBytesToRead,	// number of bytes to read
LPOVERLAPPED  lpOverlapped,	// address of offset
LPOVERLAPPED_COMPLETION_ROUTINE  lpCompletionRoutine	// address of completion routine
);
Parameters

hFile

An open handle that specifies the file entity to be read from. This file handle must have been created with the FILE_FLAG_OVERLAPPED flag and must have GENERIC_READ access to the file.

Windows NT : hFile can be any handle opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept functions.

Windows 95 : hFile can be a communications resource, mailslot, or named pipe handle opened with the FILE_FLAG_OVERLAPPED flag by CreateFile, or a socket handle returned by the socket or accept functions. Windows 95 does not support asynchronous operations on disk files.

lpBuffer

Points to a buffer that receives the data read from the file.

This buffer must remain valid for the duration of the read operation. The application should not use this buffer until the read operation is completed.

nNumberOfBytesToRead

Specifies the number of bytes to be read from the file.

lpOverlapped

Points to an OVERLAPPED data structure that supplies data to be used during the asynchronous (overlapped) file read operation.

If the file specified by hFile supports the concept of byte offsets, the caller of ReadFileEx must specify a byte offset within the file at which reading should begin. The caller specifies the byte offset by setting the OVERLAPPED structure's Offset and OffsetHigh members.

If the file entity specified by hFile does not support the concept of byte offsets — for example, if it is a named pipe — the caller must set the Offset and OffsetHigh members to zero, or ReadFileEx fails.

The ReadFileEx function ignores the OVERLAPPED structure's hEvent member. An application is free to use that member for its own purposes in the context of a ReadFileEx call. ReadFileEx signals completion of its read operation by calling, or queueing a call to, the completion routine pointed to by lpCompletionRoutine, so it does not need an event handle.

The ReadFileEx function does use the OVERLAPPED structure's Internal and InternalHigh members. An application should not set these members.

The OVERLAPPED data structure pointed to by lpOverlapped must remain valid for the duration of the read operation. It should not be a variable that can go out of scope while the file read operation is in progress.

lpCompletionRoutine

Points to the completion routine to be called when the read operation is complete and the calling thread is in an alertable wait state. For more information about the completion routine, see FileIOCompletionRoutine.

Return Value

If the function succeeds, the return value is TRUE.

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

If the function succeeds, the calling thread has an asynchronous I/O (input/output) operation pending: the overlapped read operation from the file. When this I/O operation completes, and the calling thread is blocked in an alertable wait state, the system calls the function pointed to by lpCompletionRoutine, and the wait state completes with a return code of WAIT_IO_COMPLETION.

If the function succeeds, and the file reading operation completes, but the calling thread is not in an alertable wait state, the system queues the completion routine call, holding the call until the calling thread enters an alertable wait state.

If ReadFileEx attempts to read past the end of the file, the function returns FALSE, and GetLastError returns ERROR_HANDLE_EOF.

Remarks

If a portion of the file specified by hFile is locked by another process, and the read operation specified in a call to ReadFileEx overlaps the locked portion, the call to ReadFileEx fails.

If ReadFileEx attempts to read data from a mailslot whose buffer is too small, the function returns FALSE, and GetLastError returns ERROR_INSUFFICIENT_BUFFER.

Applications must not read from nor write to the input buffer that a read operation is using until the read operation completes. A premature access to the input buffer may lead to corruption of the data read into that buffer.

The ReadFileEx function may fail if there are too many outstanding asynchronous I/O requests. In the event of such a failure, GetLastError can return ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY.

If hFile is a handle to a named pipe or other file entity that doesn't support the byte-offset concept, the Offset and OffsetHigh members of the OVERLAPPED structure pointed to by lpOverlapped must be zero, or ReadFileEx fails.

An application uses the WaitForSingleObjectEx, WaitForMultipleObjectsEx, and SleepEx functions to enter an alertable wait state. For more information about alertable waits and overlapped input/output, refer to those functions' reference and the "Synchronization"  topic mentioned previously.

See Also

CreateFile, FileIOCompletionRoutine, OVERLAPPED, ReadFile, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx


ReadPrinter

The ReadPrinter function retrieves data from the specified printer.

BOOL ReadPrinter(

HANDLE  hPrinter,	// handle of printer object
LPVOID  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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

ReadPrinter returns an error if the device or the printer is not bidirectional.

See Also

OpenPrinter


ReadProcessMemory

The ReadProcessMemory function reads memory in a specified process. The entire area to be read must be accessible, or the operation fails.

BOOL ReadProcessMemory(

HANDLE  hProcess,	// handle of the process whose memory is read
LPCVOID  lpBaseAddress,	// address to start reading
LPVOID  lpBuffer,	// address of buffer to place read data
DWORD  cbRead,	// number of bytes to read
LPDWORD  lpNumberOfBytesRead	// address of number of bytes read
);
Parameters

hProcess

Identifies an open handle of a process whose memory is read. The handle must have PROCESS_VM_READ access to the process.

lpBaseAddress

Points to the base address in the specified process to be read. Before any data transfer occurs, the system verifies that all data in the base address and memory of the specified size is accessible for read access. If this is the case, the function proceeds; otherwise, the function fails.

lpBuffer

Points to a buffer that receives the contents from the address space of the specified process.

cbRead

Specifies the requested number of bytes to read from the specified process.

lpNumberOfBytesRead

Points to the actual number of bytes transferred into the specified buffer. If lpNumberOfBytesRead is NULL, the parameter is ignored.

Return Value

If the function succeeds, the return value is TRUE.

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

The function fails if the requested read operation crosses into an area of the process that is inaccessible.

Remarks

ReadProcessMemory copies the data in the specified address range from the address space of the specified process into the specified buffer of the current process. Any process that has a handle with PROCESS_VM_READ access can call the function. The process whose address space is read is typically, but not necessarily, being debugged.

The entire area to be read must be accessible. If it is not, the function fails as noted previously.

See Also

WriteProcessMemory


RealizePalette

The RealizePalette function maps palette entries from the current logical palette to the system palette.

UINT RealizePalette(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context (DC) into which a logical palette has been selected.

Return Value

If the function succeeds, the return value is the number of entries in the logical palette mapped to the system palette.

If the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

The RealizePalette function modifies the palette for the device associated with the specified device context. If the device context is a memory DC, the color table for the bitmap selected into the DC is modified. If the device context is a display DC, the physical palette for that device is modified.

A logical color palette is a buffer between color-intensive applications and the system, allowing these applications to use as many colors as needed without interfering with colors displayed by other windows.

When an application's window has the focus and it calls the RealizePalette function, Windows attempts to realize as many of the requested colors as possible. The same is also true for applications with inactive windows.

See Also

CreatePalette, GetDeviceCaps, SelectPalette


Rectangle

The Rectangle function draws a rectangle. The rectangle is outlined by using the current pen and filled by using the current brush.

BOOL Rectangle(

HDC  hdc,	// handle of device context
int  nLeftRect,	// x-coord. of bounding rectangle's upper-left corner
int  nTopRect,	// y-coord. of bounding rectangle's upper-left corner
int  nRightRect,	// x-coord. of bounding rectangle's lower-right corner
int  nBottomRect	// y-coord. of bounding rectangle's lower-right corner
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the logical x-coordinate of the upper-left corner of the rectangle.

nTopRect

Specifies the logical y-coordinate of the upper-left corner of the rectangle.

nRightRect

Specifies the logical x-coordinate of the lower-right corner of the rectangle.

nBottomRect

Specifies the logical y-coordinate of the lower-right corner of the rectangle.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The current position is neither used nor updated by Rectangle.

See Also

RoundRect


RectInRegion

The RectInRegion function determines whether any part of the specified rectangle is within the boundaries of a region.

BOOL RectInRegion(

HRGN  hrgn,	// handle of region
CONST RECT  *lprc	// address of structure with rectangle
);
Parameters

hrgn

Identifies the region.

lprc

Points to a RECT structure containing the coordinates of the rectangle. The lower and right edges of the rectangle are not included.

Return Value

If any part of the specified rectangle lies within the boundaries of the region, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

PtInRegion, RECT


RectVisible

The RectVisible function determines whether any part of the specified rectangle lies within the clipping region of a device context.

BOOL RectVisible(

HDC  hdc,	// handle of the device context
CONST RECT  *lprc	// address of rectangle structure
);
Parameters

hdc

Identifies the device context.

lprc

Points to a RECT structure that contains the logical coordinates of the specified rectangle.

Return Value

If some portion of the specified rectangle lies within the clipping region, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

CreateRectRgn, PtVisible, RECT, SelectClipRgn


recv

The Windows Sockets recv function receives data from a socket.

int recv (

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

s

A descriptor identifying a connected socket.

buf

A buffer for the incoming data.

len

The length of buf.

flags

Specifies the way the call is made.

Return Value

If the function succeeds, recv returns the number of bytes received. If the connection has been closed, it returns zero.

If the function fails, a value of SOCKET_ERROR is returned. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAENOTCONN	The socket is not connected.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not of type SOCK_STREAM.
WSAESHUTDOWN	The socket has been shut down; it is not possible to recv on a socket after shutdown has been invoked with how set to 0 or 2.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the receive operation would block.
WSAEMSGSIZE	The datagram was too large to fit into the specified buffer and was truncated.
WSAEINVAL	The socket has not been bound with bind.
WSAECONNABORTED	The virtual circuit was aborted due to timeout or other failure.
WSAECONNRESET	The virtual circuit was reset by the remote side.
Remarks

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

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

For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the buffer supplied. If the datagram is larger than the buffer supplied, the buffer is filled with the first part of the datagram, the excess data is lost, and recv returns the error WSAEMSGSIZE.

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

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

Flags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by using a bitwise OR operation with any of the following values:

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

bind, recvfrom, send, select, shutdown, socket, WSAAsyncSelect, WSACancelBlockingCall, WSAStartup


recvfrom

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

int recvfrom (

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

s

A descriptor identifying a bound socket.

buf

A buffer for the incoming data.

len

The length of buf.

flags

Specifies the way the call is made.

from

An optional pointer to a buffer to hold the source address upon return.

fromlen

An optional pointer to the size of the from buffer.

Return Value

If the function succeeds, recvfrom returns the number of bytes received. If the connection has been closed, it returns zero.

If the function fails, a value of SOCKET_ERROR is returned. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEFAULT	The fromlen argument was invalid: the from buffer was too small to accommodate the peer address.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEINVAL	The socket has not been bound with bind.
WSAENOTCONN	The socket is not connected (SOCK_STREAM only).
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not of type SOCK_STREAM.
WSAESHUTDOWN	The socket has been shut down; it is not possible to recvfrom on a socket after shutdown has been invoked with how set to 0 or 2.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the recvfrom operation would block.
WSAEMSGSIZE	The datagram was too large to fit into the specified buffer and was truncated.
WSAECONNABORTED	The virtual circuit was aborted due to timeout or other failure.
WSAECONNRESET	The virtual circuit was reset by the remote side.
Remarks

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

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

For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the buffer supplied. If the datagram is larger than the buffer supplied, the buffer is filled with the first part of the message, the excess data is lost, and recvfrom returns the error code WSAEMSGSIZE.

If from is nonzero, and the socket is of type SOCK_DGRAM, the network address of the peer that sent the data is copied to the corresponding socket address structure. The value pointed to by fromlen is initialized to the size of this structure, and is modified on return to indicate the actual size of the address stored there.

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

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

You can use the flags parameter to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of the recvfrom function are determined by the socket options and the flags parameter. The latter is constructed by using a bitwise OR operation with any of the following values:

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

bind, recv, select, send, shutdown, socket, WSAAsyncSelect, WSACancelBlockingCall, WSAStartup


RedrawWindow

The RedrawWindow function updates the specified rectangle or region in a window's client area.

BOOL RedrawWindow(

HWND  hwnd,	// handle of window
CONST RECT  *lprcUpdate,	// address of structure with update rectangle
HRGN  hrgnUpdate,	// handle of update region
UINT  afuRedraw	// array of redraw flags
);
Parameters

hwnd

Identifies the window to be redrawn. If this parameter is NULL, the desktop window is updated.

lprcUpdate

Points to a RECT structure containing the coordinates of the update rectangle. This parameter is ignored if the hrgnUpdate parameter identifies a region.

hrgnUpdate

Identifies the update region. If both the hrgnUpdate and lprcUpdate parameters are NULL, the entire client area is added to the update region.

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 (invalidation)	Description
RDW_ERASE	Causes the window to receive a WM_ERASEBKGND message when the window is repainted. The RDW_INVALIDATE flag must also be specified; otherwise, RDW_ERASE has no effect.
RDW_FRAME	Causes any part of the nonclient area of the window that intersects the update region to receive a WM_NCPAINT message. The RDW_INVALIDATE flag must also be specified; otherwise, RDW_FRAME has no effect. The WM_NCPAINT message is typically not sent during the execution of RedrawWindow unless either RDW_UPDATENOW or RDW_ERASENOW is specified.
RDW_INTERNALPAINT	Causes a WM_PAINT message to be posted to the window regardless of whether any portion of the window is invalid.
RDW_INVALIDATE	Invalidates lprcUpdate or hrgnUpdate (only one may be non-NULL). If both are NULL, the entire window is invalidated.
The following flags are used to validate the window:

Flag (validation)	Description
RDW_NOERASE	Suppresses any pending WM_ERASEBKGND messages.
RDW_NOFRAME	Suppresses any pending WM_NCPAINT messages. This flag must be used with RDW_VALIDATE and is typically used with RDW_NOCHILDREN. RDW_NOFRAME should be used with care, as it could cause parts of a window to be painted improperly.
RDW_NOINTERNALPAINT	Suppresses any pending internal WM_PAINT messages. This flag does not affect WM_PAINT messages resulting from a non-NULL update area.
RDW_VALIDATE	Validates lprcUpdate or hrgnUpdate (only one may be non-NULL). If both are NULL, the entire window is validated. This flag does not affect internal WM_PAINT messages.
The following flags control when repainting occurs. RedrawWindow will not repaint unless one of these flags is specified.

Flag	Description
RDW_ERASENOW	Causes the affected windows (as specified by the RDW_ALLCHILDREN and RDW_NOCHILDREN flags) to receive WM_NCPAINT and WM_ERASEBKGND messages, if necessary, before the function returns. WM_PAINT messages are received at the ordinary time.
RDW_UPDATENOW	Causes the affected windows (as specified by the RDW_ALLCHILDREN and RDW_NOCHILDREN flags) to receive WM_NCPAINT, WM_ERASEBKGND, and WM_PAINT messages, if necessary, before the function returns.
By default, the windows affected by RedrawWindow depend on whether the given window has the WS_CLIPCHILDREN style. Child windows that are not the WS_CLIPCHILDREN style are unaffected; non-WS_CLIPCHILDREN windows are recursively validated or invalidated until a WS_CLIPCHILDREN window is encountered. The following flags control which windows are affected by the RedrawWindow function:

Flag	Description
RDW_ALLCHILDREN	Includes child windows, if any, in the repainting operation.
RDW_NOCHILDREN	Excludes child windows, if any, from the repainting operation.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

When RedrawWindow is used to invalidate part of the desktop window, the desktop window does not receive a WM_PAINT message. To repaint the desktop, an application uses the RDW_ERASE flag to generate a WM_ERASEBKGND message.

See Also

GetUpdateRect, GetUpdateRgn, InvalidateRect, InvalidateRgn, RECT, UpdateWindow


RegCloseKey

The RegCloseKey function releases the handle of the specified key.

LONG RegCloseKey(

HKEY  hKey	// handle of key to close
);
Parameters

hKey

Identifies the open key to close.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The handle for a specified key should not be used after it has been closed, because it will no longer be valid. Key handles should not be left open any longer than necessary.

The RegCloseKey function does not necessarily write information to the registry before returning; it can take as much as several seconds for the cache to be flushed to the hard disk. If an application must explicitly write registry information to the hard disk, it can use the RegFlushKey function. RegFlushKey, however, uses many system resources and should be called only when necessary.

See Also

RegCreateKey, RegCreateKeyEx, RegDeleteKey, RegFlushKey, RegOpenKey, RegOpenKeyEx, RegSetValue, RegSetValueEx


RegConnectRegistry

The RegConnectRegistry function establishes a connection to a predefined registry handle on another computer.

LONG RegConnectRegistry(

LPTSTR  lpszComputerName,	// address of name of remote computer
HKEY  hKey,	// predefined registry handle
PHKEY  phkResult	// address of buffer for remote registry handle
);
Parameters

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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

When a handle returned by RegConnectRegistry is no longer needed, it should be closed by calling RegCloseKey.

See Also

RegCloseKey


RegCreateKey

The RegCreateKey function creates the specified key. If the key already exists in the registry, the function opens it. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegCreateKeyEx function.

LONG RegCreateKey(

HKEY  hKey,	// handle of an open key
LPCTSTR  lpszSubKey,	// address of name of subkey to open
PHKEY  phkResult	// address of buffer for opened handle
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The key opened or created by this function is a subkey of the key identified by hKey.

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 by using phkResult is the same hKey handle passed in to the function.

phkResult

Points to a variable that receives the handle of the opened or created key.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

An application can use the RegCreateKey function to create several keys at once. For example, an application can create a subkey four levels deep at the same time as the three preceding subkeys by specifying a string of the following form for the 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).

If the lpszSubKey parameter is the address of an empty string, the function opens and then passes back the key identified by the hKey parameter.

See Also

RegCloseKey, RegCreateKeyEx, RegDeleteKey, RegOpenKey, RegOpenKeyEx, RegSetValue


RegCreateKeyEx

The RegCreateKeyEx function creates the specified key. If the key already exists in the registry, the function opens it.

LONG RegCreateKeyEx(

HKEY  hKey,	// handle of an open key
LPCTSTR  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 disposition value buffer
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The key opened or created by the RegCreateKeyEx function is a subkey of the key identified by the hKey parameter.

lpszSubKey

Points to a null-terminated string specifying the name of a subkey that this function opens or creates. The subkey specified must be a subkey of the key identified by the hKey parameter. This subkey must not begin with the backslash character ('\'). This parameter cannot be NULL.

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 keys that are not volatile.
By default, keys are not volatile. This option is ignored if the key already exists.

The RegSaveKey function only saves nonvolatile 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.
Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The key that the RegCreateKeyEx function creates has no values. An application can use the RegSetValue or RegSetValueEx function to set key values.

The key identified by the hKey parameter must have been opened with KEY_CREATE_SUB_KEY access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

An application cannot create a key under HKEY_USERS or HKEY_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, SECURITY_ATTRIBUTES


RegDeleteKey

Windows 95: The RegDeleteKey function deletes a key and all its descendents.

Windows NT: The RegDeleteKey function deletes the specified key. This function cannot delete a key that has subkeys.

LONG RegDeleteKey(

HKEY  hKey,	// handle of open key
LPCTSTR  lpszSubKey	// address of name of subkey to delete
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The key specified by the 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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

If the function succeeds, RegDeleteKey removes the specified key from the registry. The entire key, including all of its values, is removed.

To open the key, use the RegCreateKeyEx or RegOpenKeyEx function. Do not use the RegCreateKey or RegOpenKey functions.

See Also

RegCloseKey, RegCreateKeyEx, RegOpenKeyEx


RegDeleteValue

The RegDeleteValue function removes a named value from the specified registry key.

LONG RegDeleteValue(

HKEY  hKey,	// handle of key
LPTSTR  lpszValue	// address of value name
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access (KEY_WRITE access includes KEY_SET_VALUE access).

See Also

RegSetValue, RegSetValueEx


RegEnumKey

The RegEnumKey function enumerates subkeys of the specified open registry key. The function retrieves the name of one subkey each time it is called. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegEnumKeyEx function.

LONG RegEnumKey(

HKEY  hKey,	// handle of key to query
DWORD  iSubKey,	// index of subkey to query
LPTSTR  lpszName,	// address of buffer for subkey name
DWORD  cchName	// size of subkey buffer
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The keys returned are relative to the key identified by hKey.

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 terminating 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 (MAX_PATH + 1) characters.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

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

The RegEnumKeyEx function enumerates subkeys of the specified open registry key. The function retrieves information about one subkey each time it is called. Unlike the RegEnumKey function, RegEnumKeyEx retrieves the class name of the subkey and the time it was last modified.

LONG RegEnumKeyEx(

HKEY  hKey,	// handle of key to enumerate
DWORD  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
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The enumerated keys are subkeys of the key identified by hKey.

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

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

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

RegCreateKeyEx, RegDeleteKey, RegEnumKey, RegOpenKeyEx, RegQueryInfoKey


RegEnumValue

The RegEnumValue function enumerates the values for the specified open registry key. The function copies one indexed value name and data block for the key each time it is called.

LONG RegEnumValue(

HKEY  hKey,	// handle of key to query
DWORD  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
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The enumerated values are associated with the key identified by hKey.

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 by 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 and Windows 95.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order 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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

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 RegQueryInfoKey function.

While using RegEnumValue, an application should not call any registration functions that might change the key being queried.

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

To determine the maximum size of the name and data buffers, use the RegQueryInfoKey function.

See Also

RegCreateKeyEx, RegEnumKey, RegEnumKeyEx, RegOpenKeyEx, RegQueryInfoKey


RegFlushKey

The RegFlushKey function writes all the attributes of the specified open key into the registry.

LONG RegFlushKey(

HKEY  hKey	// handle of key to write
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

It is not necessary to call RegFlushKey to change a key. Registry changes are flushed to disk by the registry using its lazy flusher. Registry changes are also flushed to disk at system shutdown.

Unlike RegCloseKey, the RegFlushKey function returns only when all the data has been written to the registry.

The RegFlushKey function may also write out parts of or all of the other keys. Calling this function excessively can have a negative effect on an application's performance.

An application should only call RegFlushKey if it requires absolute certainty that registry changes are on disk. In general, RegFlushKey rarely, if ever, need be used.

See Also

RegCloseKey, RegDeleteKey


RegGetKeySecurity

The RegGetKeySecurity function retrieves a copy of the security descriptor protecting the specified open registry key.

LONG RegGetKeySecurity(

HKEY  hKey,	// open handle of key to set
SECURITY_INFORMATION  SecInf,	// descriptor contents
PSECURITY_DESCRIPTOR  pSecDesc,	// address of descriptor for key
LPDWORD  lpcbSecDesc	// address of size of buffer and descriptor
);
Parameters

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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

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 specified key, the calling process must have been granted READ_CONTROL access when the key was opened, or it must be the owner of the key. (READ_CONTROL access is granted by the KEY_READ, KEY_WRITE, KEY_EXECUTE, and KEY_ALL_ACCESS access rights.) In addition, the caller must have the SE_SECURITY_NAME privilege to read the system access-control list (SACL).

See Also

RegDeleteKey, RegOpenKeyEx, RegSetKeySecurity, SECURITY_INFORMATION


RegisterClass

The RegisterClass function registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function.

ATOM RegisterClass(

CONST WNDCLASS  *lpwc	// address of structure with class data
);
Parameters

lpwc

Points to a WNDCLASS structure. You must fill the structure with the appropriate class attributes before passing it to the function.

Return Value

If the function succeeds, the return value is an atom that uniquely identifies the class being registered.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

All window classes that an application registers are unregistered when it terminates.

See Also

CreateWindow, CreateWindowEx, GetClassInfo, GetClassName, UnregisterClass, WindowProc, WNDCLASS


RegisterClassEx  (preliminaryWindows 95)
RegisterClassEx  (preliminary−Windows 95)

The RegisterClassEx function registers a window class for subsequent use in calls to the CreateWindow or CreateWindowEx function.

ATOM RegisterClassEx(

CONST WNDCLASSEX FAR  *lpwcx	// address of structure with class data
);
Parameters

lpwcx

Points to a WNDCLASSEX structure. You must fill the structure with the appropriate class attributes before passing it to the function.

Return Value

If the function succeeds, the return value is an atom that uniquely identifies the class being registered.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

All window classes that an application registers are unregistered when it terminates.

See Also

CreateWindow, CreateWindowEx, GetClassInfoEx, GetClassName, UnregisterClass, WindowProc


RegisterClipboardFormat

The RegisterClipboardFormat function registers a new clipboard format. This format can then be used as a valid clipboard format.

UINT RegisterClipboardFormat(

LPCTSTR  lpszFormat	// address of name string
);
Parameters

lpszFormat

Points to a null-terminated string that names the new format.

Return Value

If the function succeeds, the return value identifies the registered clipboard format.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If a registered format with the specified name already exists, a new format is not registered and the return value identifies the existing format. This enables more than one application to copy and paste data using the same registered clipboard format.

Registered clipboard formats are identified by values in the range 0xC000 through 0xFFFF.

See Also

CountClipboardFormats, EnumClipboardFormats, GetClipboardFormatName


RegisterDialogClasses

The RegisterDialogClasses function registers any nonstandard window classes required by a screen saver's configuration dialog box.

BOOL RegisterDialogClasses(

HANDLE  hinst	// handle of application instance
);
Parameters

hinst

Identifies an instance of the module registering the window classes.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The RegisterDialogClasses function should not be exported. It is called by routines defined in the SCRNSAVE.LIB file.

If a screen saver does not register any special window classes for the configuration dialog box, the RegisterDialogClasses function must return TRUE.

See Also

ScreenSaverConfigureDialog


RegisterEventSource

The RegisterEventSource function returns a handle that can be used with the ReportEvent function to log an event.

Any source name can be used; it will be carried in the event log record so that Event Viewer can use it for filtering.

HANDLE RegisterEventSource(

LPCTSTR  lpszUNCServer,	// server name for source
LPCTSTR  lpszSource	// source name for registered handle
);
Parameters

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.

Return Value

If the function succeeds, the return value is a handle that can be used with the ReportEvent function.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

See Also

DeregisterEventSource, ReportEvent


RegisterHotKey

The RegisterHotKey function defines a hot key for the current thread.

BOOL RegisterHotKey(

HWND  hwnd,	// window to receive hot-key notification
int  idHotKey,	// identifier of hot key
UINT  fuModifiers,	// key-modifier flags
UINT  uVirtKey	// virtual-key code
);
Parameters

hwnd

Identifies the window that will receive WM_HOTKEY messages generated by the hot key. If this parameter is NULL, WM_HOTKEY messages are posted to the message queue of the calling thread and must be processed in the message loop.

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.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

When a key is pressed, the system looks for a match against all thread hot keys. Upon finding a match, the system posts the WM_HOTKEY message to the message queue of the thread that registered the hot key. This message is posted to the beginning of the queue so it is removed by the next iteration of the message loop.

This function cannot associate a hot key with a window created by another thread.

RegisterHotKey fails if the keystrokes specified for the hot key have already been registered by another hot key.

If the window identified by the hwnd parameter already registered a hot key with the same identifier as that specified by the idHotKey parameter, the new values for the fuModifiers and uVirtKey parameters replace the previously specified values for these parameters.

See Also

GlobalAddAtom, UnregisterHotKey, WM_HOTKEY


RegisterServiceCtrlHandler

The RegisterServiceCtrlHandler function registers a function to handle service control requests for a service.

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandler(

LPCTSTR  lpszServiceName,	// address of name of service
LPHANDLER_FUNCTION  lpHandlerProc	// address of handler function
);
Parameters

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.

Return Value

If the function succeeds, the return value is a service status handle.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_INVALID_NAME	The specified service name is invalid.
ERROR_SERVICE_DOES_NOT_EXIST	The specified service does not exist.
Remarks

The ServiceMain function of a new service should immediately call the RegisterServiceCtrlHandler function to register a control handling function with the control dispatcher. This enables the control dispatcher to invoke the specified function when it receives control requests for this service. The threads of the calling process can use the service status handle returned by this function to identify the service in subsequent calls to the SetServiceStatus function.

This function must be called before the first SetServiceStatus call because it returns a service status handle for the caller to use so that no other service can inadvertently set this service's status, which is maintained by the service control manager. It also needs to be called before the first SetServiceStatus so that a control handler is in place to field control requests by the time the service specifies the controls it accepts through the SetServiceStatus function.

When the control handler function is invoked with a control request, it must call SetServiceStatus to notify the service control manager of its latest status, regardless of whether the status of the service has changed.

The service status handle does not have to be closed.

See Also

CreateService, Handler, ServiceMain, SetServiceStatus


RegisterWindowMessage

The RegisterWindowMessage function defines a new window message that is guaranteed to be unique throughout the system. The returned message value can be used when calling the SendMessage or PostMessage function.

UINT RegisterWindowMessage(

LPCTSTR  lpsz	// address of message string
);
Parameters

lpsz

Points to a null-terminated string that specifies the message to be registered.

Return Value

If the message is successfully registered, the return value is a message identifier in the range 0xC000 through 0xFFFF.

If the function fails, the return value is zero.

Remarks

The RegisterWindowMessage function is typically used to register messages for communicating between two cooperating applications.

If two different applications register the same message string, the applications return the same message value. The message remains registered until the Windows session ends.

Only use RegisterWindowMessage when more than one application must process the same message. For sending private messages within a window class, an application can use any integer in the range WM_USER through 0x7FFF. (Messages in this range are private to a window class, not to an application. For example, predefined control classes such as BUTTON, EDIT, LISTBOX, and COMBOBOX may use values in this range.)

See Also

PostAppMessage, PostMessage, SendMessage


RegLoadKey

The RegLoadKey function creates a subkey under HKEY_USER or HKEY_LOCAL_MACHINE and stores registration information from a specified file into that subkey. This registration information is in the form of a hive. A hive is a discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy. A hive is backed by a single file and .LOG file.

LONG RegLoadKey(

HKEY  hKey,	// handle of open key
LPCTSTR  lpszSubKey,	// address of name of subkey
LPCTSTR  lpszFile	// address of filename for registry information
);
Parameters

hKey

Specifies the key where the subkey will be created. This can be a predefined reserved handle value, or a handle returned by a call to RegConnectRegistry. The predefined reserved handle values are:

HKEY_LOCAL_MACHINE
HKEY_USERS

This function always loads information at the top of the registry hierarchy. The HKEY_CLASSES_ROOT and HKEY_CURRENT_USER handle values cannot be specified for this parameter, because they represent subsets of the HKEY_LOCAL_MACHINE and HKEY_USERS handle values, respectively.

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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

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

RegConnectRegistry, RegDeleteKey, RegReplaceKey, RegRestoreKey, RegSaveKey, RegUnloadKey


RegNotifyChangeKeyValue

The RegNotifyChangeKeyValue function indicates when a registry key or any of its subkeys has changed.

LONG RegNotifyChangeKeyValue(

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
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

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 specified event. When this parameter is FALSE, the function does not return until a change has occurred.

If hEvent does not specify a valid event, the fAsync parameter cannot be TRUE.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

If the key identified by the hKey parameter is closed, the event is signaled. This means that an application should not depend on the key being open after returning from a wait operation on the event.

RegNotifyChangeKeyValue does not work with remote handles. If RegNotifyChangeKeyValue is called with an hKey value that is a remote handle, it returns ERROR_INVALID_HANDLE.

See Also

RegDeleteKey, RegEnumKey, RegEnumKeyEx, RegEnumValue, RegQueryInfoKey, RegQueryValue, RegQueryValueEx


RegOpenKey

The RegOpenKey function opens the specified key. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegOpenKeyEx function.

LONG RegOpenKey(

HKEY  hKey,	// handle of open key
LPCTSTR  lpszSubKey,	// address of name of subkey to open
PHKEY  phkResult	// address of handle of open key
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

The key opened by the RegOpenKey function is a subkey of the key identified by hKey.

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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The RegOpenKey function uses the default security access mask to open a key. If opening the key requires a different mask, the function fails, returning ERROR_ACCESS_DENIED. An application should use the RegOpenKeyEx function to specify an access mask in this situation.

Unlike the RegCreateKey function, RegOpenKey does not create the specified key if the key does not exist in the database.

See Also

RegCreateKey, RegCreateKeyEx, RegDeleteKey, RegOpenKeyEx


RegOpenKeyEx

The RegOpenKeyEx function opens the specified key.

LONG RegOpenKeyEx(

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
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

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

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

Unlike the RegCreateKeyEx function, the RegOpenKeyEx function does not create the specified key if the key does not exist in the registry.

See Also

RegCreateKeyEx, RegDeleteKey, RegOpenKey


RegQueryInfoKey

The RegQueryInfoKey function retrieves information about a specified registry key.

LONG RegQueryInfoKey (

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
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access (KEY_READ access includes KEY_QUERY_VALUE access).

See Also

FILETIME, RegDeleteKey, RegEnumKey, RegEnumKeyEx, RegEnumValue, RegQueryValue, RegQueryValueEx


RegQueryMultipleValues

The RegQueryMultipleValues function retrieves the type and data for a list of value names associated with an open registry key.

LONG RegQueryMultipleValues(hKey, lpszSubKey, val_list, num_vals,
    lpValueBuf, ldwTotsize)
HKEY hKey;	// handle of key to query
PVALENT val_list;	// address of array of value entry structures
DWORD num_vals;	// size of array of value entry structures
LPTSTR lpValueBuf;	// address of buffer for value information
LPDWORD ldwTotsize;	// address of size of value buffer

Parameters

hKey

Identifies a currently open key or any of the pre-defined reserved handle values:

HKEY_CLASSES_ROOT
HEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

val_list

Address of an array of VALENT structures that describe one or more value entries. When the function returns, val_list contains an element for each value entry. The VALENT structure has the following format:

typedef struct value_ent {  /* val */

    LPCTSTR  ve_valuename;

    DWORD    ve_valuelen;

    DWORD    ve_valueptr;

    DWORD    ve_type;

} RECT;

num_vals

Specifies the size, in bytes, of the array pointed to by the val_list parameter. If num_vals is not a multiple of the size of a VALENT structure, the extra space in the array is ignored. If the buffer pointed to by the val_list parameter is too small, num_vals receives the required size, in bytes, and the buffer is filled to the size specified by num_vals when the function was called; extra bytes are ignored.

lpValueBuf

Pointer to a buffer that receives value names and data. The data in the buffer is doubleword-aligned; padding is inserted as necessary.

ldwTotsize

Pointer to a value that specifies the size of the output buffer pointed to by the lpValueBuf parameter. When the function returns, ldwTotsize contains the number of bytes copied to the buffer, including padding. If the buffer is too small, ldwTotsize receives the required size, in bytes, and the buffer is filled to the size specified by ldwTotsize.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS..

If the function fails, the return value is is an error value that can include one of the following:

Value	Meaning
ERROR_INSUFFICIENT_BUFFER	The buffer pointed to by val_list or lpValueBuf was too small.
ERROR_CANTREAD	RegQueryMultipleValues cannot instantiate or access the provider of the dynamic key.
ERROR_TRANSFER_TOO_LONG	The total length of the requested data (num_vals + ldwTotSize) is more than the system limit of one megabyte. In this case, RegQueryMultipleValues returns only the first one megabyte of data.
Remarks

The RegQueryMultipleValues function allows an application to query one or more values of a static or dynamic key. If the target key is a static key, the system provides all of the values in an atomic fashion. To prevent excessive serialization, the aggregate data returned by the function can not exceed one megabyte.

If the target key is a dynamic key, its provider must provide all the values in an atomic fashion. This means the provider should fill the results buffer synchronously, providing a consistent view of all the values in the buffer while avoiding excessive serialization. The provider can provide at most one megabyte of total output data during an atomic call to this function.

RegQueryMultipleValues is supported remotely; that is, the hKey parameter passed to the function can refer to a remote computer.


RegQueryValue

The RegQueryValue function retrieves the value associated with the unnamed value for a specified key in the registry. Values in the registry have name, type, and data components. This function retrieves the data for a key's first value that has a NULL name. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegQueryValueEx function.

LONG RegQueryValue(

HKEY  hKey,	// handle of key to query
LPCTSTR  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
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

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 terminating null character, into the variable pointed to by pcbValue. This lets an application determine how to best preallocate 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 includes the size of the terminating null character in the string.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access (KEY_READ access includes KEY_QUERY_VALUE access).

If the ANSI version of this function is used (either by explicitly calling RegQueryValue or by not defining Unicode before including the WINDOWS.H file), this function converts the stored Unicode string to an ANSI string before copying it to the buffer specified by the lpszValue parameter.

See Also

RegEnumKey, RegEnumKeyEx, RegEnumValue, RegQueryInfoKey, RegQueryValueEx, RegSetValue, RegSetValueEx


RegQueryValueEx

The RegQueryValueEx function retrieves the type and data for a specified value name associated with an open registry key.

LONG RegQueryValueEx(

HKEY  hKey,	// handle of key to query
LPTSTR  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
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

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 and Windows 95.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order 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, in the variable pointed to by lpcbData. This lets an application determine the best way to allocate a buffer for the value key's data.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, then lpData will also include the size of the terminating null character.

The lpcbData parameter can be NULL only if lpbData is NULL.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The key identified by hKey must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

This function does not expand the environment-variable names in the value data when the value type is REG_EXPAND_SZ. The ExpandEnvironmentStrings function can be used to expand the environment-variable names.

If the value data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, and the ANSI version of this function is used (either by explicitly calling RegQueryValueEx or by not defining Unicode before including the WINDOWS.H file), this function converts the stored Unicode string to an ANSI string before copying it to the buffer pointed to by 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, RegCreateKeyEx, RegEnumKey, RegEnumKeyEx, RegEnumValue, RegOpenKeyEx, RegQueryInfoKey, RegQueryValue


RegReplaceKey

The RegReplaceKey function replaces the file backing a key and all its subkeys with another file, so that when the system is next started, the key and subkeys will have the values stored in the new file.

LONG RegReplaceKey(

HKEY  hKey,	// handle of open key
LPCTSTR  lpSubKey,	// address of name of subkey
LPCTSTR  lpNewFile,	// address of filename for file with new data
LPCTSTR  lpOldFile	// address of filename for backup file
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpSubKey

Points to a null-terminated string containing the name of a key whose subkeys and values are replaced by this function. This key must be a subkey of the key identified by the hKey parameter. This parameter can be NULL.

The selected key must be the root of a hive; that is, it must be an immediate descendent of HKEY_LOCAL_MACHINE or HKEY_USERS.

lpNewFile

Points to a null-terminated string containing the name of the file with registration information. This file is typically created by using the RegSaveKey function. Under the file allocation table (FAT) file system, the filename may not have an extension.

lpOldFile

Points to a null-terminated string containing the name of a file that receives a backup copy of the registry information being replaced. If this file is created under the FAT file system, it should not have an extension.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The file specified by the lpNewFile parameter remains open until the system is restarted.

A process must have the SE_RESTORE_NAME privilege to call this function.

If hKey is a handle returned by RegConnectRegistry, then the paths specified in lpNewFile and lpOldFile are relative to the remote computer.

See Also

RegConnectRegistry, RegDeleteKey, RegLoadKey, RegRestoreKey


RegRestoreKey

The RegRestoreKey function reads the registry information in a specified file and copies it over the specified key. This registry information may be in the form of a key and multiple levels of subkeys.

LONG RegRestoreKey(

HKEY  hKey,	// handle of key where restore begins
LPCTSTR  lpszFile,	// address of filename containing saved tree
DWORD  fdw	// optional flags
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

Any information contained in this key and its descendent keys is overwritten by the information in the file pointed to by the 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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

If the calling process does not have the SE_RESTORE_NAME privilege or if any subkeys of the hKey parameter are open, RegRestoreKey fails.

This function replaces the keys and values below the specified key with the keys and values that are subsidiary to the top-level key in the file, no matter what the name of the top-level key in the file might be. For example, hKey might identify a key A with subkeys B and C, while the 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

The RegSaveKey function saves the specified key and all of its subkeys and values to a new file.

LONG RegSaveKey(

HKEY  hKey,	// handle of key where save begins
LPCTSTR  lpszFile,	// address of filename to save to
LPSECURITY_ATTRIBUTES  lpsa	// address of security structure
);
Parameters

hKey

Specifies a handle of the key where the save operation is to begin, or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpszFile

Points to a null-terminated string containing the name of the file in which the specified key and subkeys are saved. This file cannot already exist. If this filename includes an extension, it cannot be used on file allocation table (FAT) file systems by the RegLoadKey, RegReplaceKey, or RegRestoreKey function.

lpsa

Points to a SECURITY_ATTRIBUTES structure for the new file. If this parameter is NULL, the file receives a default security descriptor.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

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 possess the SeBackupPrivilege security privilege.

The RegSaveKey function saves only nonvolatile keys. It does not save volatile keys. A key is made volatile or nonvolatile at its creation; see RegCreateKeyEx.

See Also

RegCreateKeyEx, RegDeleteKey, RegLoadKey, RegReplaceKey, RegRestoreKey, SECURITY_ATTRIBUTES


RegSetKeySecurity

The RegSetKeySecurity function sets the security of an open registry key.

LONG RegSetKeySecurity(

HKEY  hKey,	// open handle of key to set
SECURITY_INFORMATION  si,	// descriptor contents
PSECURITY_DESCRIPTOR  psd	// address of descriptor for key
);
Parameters

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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

This function succeeds only if the following conditions are met:

•	If the key's owner or group is being set, the caller must have WRITE_OWNER permission or have the SE_TAKE_OWNERSHIP_NAME privilege.

•	If the key's discretionary access-control list (DACL) is being set, the caller must have WRITE_DAC permission or be the object's owner.

•	If the key's system access-control list (SACL) is being set, the caller must have the SE_SECURITY_NAME privilege.

If hKey is one of the predefined keys, the predefined key should be closed with RegCloseKey. That ensures that the new security information is in effect the next time the predefined key is referenced.

See Also

RegCloseKey, RegDeleteKey, RegGetKeySecurity, SECURITY_INFORMATION


RegSetValue

The RegSetValue function associates a value with a specified key. This value must be a text string and cannot have a name. This function is provided for compatibility with Windows version 3.1. Win32-based applications should use the RegSetValueEx function, which allows an application to set any number of named values of any data type.

LONG RegSetValue(

HKEY  hKey,	// handle of key to set value for
LPCTSTR  lpSubKey,	// address of subkey name
DWORD  dwType,	// type of value
LPCTSTR  lpData,	// address of value data
DWORD  cbData	// size of value data
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpSubKey

Points to a null-terminated string containing the name of the subkey with which a value is associated. This parameter can be null or a pointer to an empty string. In this case, the value will be added to the key identified by the hKey parameter.

dwType

Specifies the type of information to be stored. This parameter must be the REG_SZ type. To store other data types, use the RegSetValueEx function.

lpData

Points to a null-terminated string containing the value to set for the specified key.

cbData

Specifies the length, in characters, of the string pointed to by the lpData parameter, not including the terminating null character.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

If the key specified by the lpSubKey parameter does not exist, the RegSetValue function creates it.

Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the registry. This helps the registry perform efficiently.

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function. If the ANSI version of this function is used (either by explicitly calling RegSetValue or by not defining Unicode before including the WINDOWS.H file), the lpData parameter must be an ANSI character string. The string is converted to Unicode before it is stored in the registry.

See Also

RegCreateKeyEx, RegFlushKey, RegOpenKeyEx, RegQueryValue, RegQueryValueEx, RegSetValueEx


RegSetValueEx

The RegSetValueEx function stores data in the value field of an open registry key. It can also set additional value and type information for the specified key.

LONG RegSetValueEx(

HKEY  hKey,	// handle of key to set value for
LPCTSTR  lpValueName,	// address of value to set
DWORD  Reserved,	// reserved
DWORD  dwType,	// flag for value type
CONST BYTE *  lpData,	// address of value data
DWORD  cbData	// size of value data
);
Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

HKEY_CLASSES_ROOT
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_USERS

lpValueName

Points to a string containing the name of the value to set. If a value with this name is not already present in the key, the function adds it to the key.

If this parameter is NULL or points to an empty string and the dwType parameter is the REG_SZ type, this function sets the same value the RegSetValue function would set.

Reserved

Reserved; must be zero.

dwType

Specifies the type of information to be stored as the value's data. This parameter can be one of the following values:

Value	Meaning
REG_BINARY	Binary data in any form.
REG_DWORD	A 32-bit number.
REG_DWORD_LITTLE_ENDIAN	A 32-bit number in little-endian format (same as REG_DWORD). In little-endian format, the most significant byte of a word is the high-order word. This is the most common format for computers running Windows NT and Windows 95.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order 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.
lpData

Points to a buffer containing the data to be stored with the specified value name.

cbData

Specifies the size, in bytes, of the information pointed to by the lpData parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, cbData must include the size of the terminating null character.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the registry. This helps the registry perform efficiently. Application elements such as icons, bitmaps, and executable files should be stored as files and not be placed in the registry.

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access. To open the key, use the RegCreateKeyEx or RegOpenKeyEx function.

If dwType is the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type and the ANSI version of this function is used (either by explicitly calling RegSetValueEx or by not defining Unicode before including the WINDOWS.H file), the data pointed to by the lpData parameter must be an ANSI character string. The string is converted to Unicode before it is stored in the registry.

See Also

RegCreateKeyEx, RegFlushKey, RegOpenKeyEx, RegQueryValue, RegQueryValueEx, RegSetValue


RegUnLoadKey

The RegUnLoadKey function unloads the specified key and subkeys from the registry.

LONG RegUnLoadKey(

HKEY  hKey,	// handle of open key
LPCTSTR  lpszSubKey	// address of name of subkey to unload
);
Parameters

hKey

Specifies the key to be unloaded. This can be a predefined reserved handle value, or a handle returned by a call to RegConnectRegistry. The predefined reserved handle values are:

HKEY_LOCAL_MACHINE
HKEY_USERS

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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

This function removes a hive from the registry but does not modify the file containing the registry information. A hive is a discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy.

Windows NT only: The calling process must have the SE_RESTORE_NAME privilege.

See Also

RegConnectRegistry, RegDeleteKey, RegLoadKey, RegRestoreKey


ReleaseCapture

The ReleaseCapture function releases the mouse capture from a window in the current thread and restores normal mouse input processing. A window that has captured the mouse receives all mouse input, regardless of the position of the cursor, except when a mouse button is clicked while the cursor hot spot is in the window of another thread.

BOOL ReleaseCapture(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

An application calls this function after calling the SetCapture function.

Windows 95 only: Calling this function causes the window that is losing the mouse capture to receive a WM_CAPTURECHANGED message.

See Also

GetCapture, SetCapture


ReleaseDC

The ReleaseDC function releases a device context (DC), freeing it for use by other applications. The effect of the ReleaseDC function depends on the type of device context. It frees only common and window device contexts. It has no effect on class or private device contexts.

int ReleaseDC(

HWND  hwnd,	// handle of window
HDC  hdc	// handle of device context
);
Parameters

hwnd

Identifies the window whose device context is to be released.

hdc

Identifies the device context to be released.

Return Value

The return value specifies whether the device context is released. If the device context is released, the return value is 1.

If the device context is not released, the return value is zero.

Remarks

The application must call the ReleaseDC function for each call to the GetWindowDC function and for each call to the GetDC function that retrieves a common device context.

An application cannot use the ReleaseDC function to release a device context that was created by calling the CreateDC function; instead, it must use the DeleteDC function.

See Also

CreateDC, DeleteDC, GetDC, GetWindowDC


ReleaseMutex

The ReleaseMutex function releases ownership of the specified mutex object.

BOOL ReleaseMutex(

HANDLE  hMutex	// handle of mutex object
);
Parameters

hMutex

Identifies the mutex object. The CreateMutex or OpenMutex function returns this handle.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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

The ReleaseSemaphore function increases the count of the specified semaphore object by a specified amount.

BOOL ReleaseSemaphore(

HANDLE  hSemaphore,	// handle of the semaphore object
LONG  cReleaseCount,	// amount to add to current count
LPLONG  lplPreviousCount	// address of previous count
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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

The RemoveDirectory function deletes an existing empty directory.

BOOL RemoveDirectory(

LPCTSTR  lpszDir	// address of directory to remove
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateDirectory


RemoveFontResource

The RemoveFontResource function removes the fonts in the specified file from the Windows font table.

BOOL RemoveFontResource(

LPCTSTR  lpFileName	// address of font-resource filename
);
Parameters

lpFileName

Points to a null-terminated string that names a font resource file.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application that adds or removes fonts from the Windows public font table should notify other windows of the change by sending a WM_FONTCHANGE message to all top-level windows in the system. The application sends this message by calling the SendMessage function with the hwnd parameter set to HWND_BROADCAST.

If there are outstanding references to a font, the associated resource remains loaded until no device context is using it.

See Also

AddFontResource, SendMessage


RemoveMenu

The RemoveMenu function deletes a menu item from the specified menu. If the menu item 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.

BOOL RemoveMenu(

HMENU  hmenu,	// handle of menu
UINT  uItem,	// menu item identifier or position
UINT  fuFlags	// menu item flag
);
Parameters

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 uItem gives the identifier of the menu item. If neither the MF_BYCOMMAND nor MF_BYPOSITION flag is specified, the MF_BYCOMMAND flag is the default flag.
MF_BYPOSITION	Indicates that uItem gives the zero-based relative position of the menu item.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The application must call the DrawMenuBar function whenever a menu changes, whether or not the menu is in a displayed window.

See Also

CreatePopupMenu, DeleteMenu, DrawMenuBar, GetSubMenu


RemoveProp

The RemoveProp function removes an entry from the property list of the specified window. The specified character string identifies the entry to be removed.

HANDLE RemoveProp(

HWND  hwnd,	// handle of window
LPCTSTR  lpsz	// atom or address of string
);
Parameters

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.

Return Value

If the function succeeds, the return value identifies the specified string. If the string cannot be found in the specified property list, the return value is NULL.

Remarks

An application must free the data handles associated with entries removed from a property list. The application can remove only those properties it has added. It must not remove properties added by other applications or by Windows itself.

The RemoveProp function returns the data handle associated with the string so that the application can free the data associated with the handle.

See Also

AddAtom, EnumProps, EnumPropsEx, GetProp, SetProp


ReplaceText

The ReplaceText function creates a system-defined modeless dialog box that enables the user to find and replace text within a document.

HWND ReplaceText(

LPFINDREPLACE  lpfr	// address of structure with initialization data
);
Parameters

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.

Return Value

If the function succeeds, the return value is the window handle of the dialog box. It is NULL if an error occurs.

The CommDlgExtendedError function can be used to get extended error information, which may be one of the following values:

CDERR_FINDRESFAILURE	CDERR_MEMLOCKFAILURE
CDERR_INITIALIZATION	CDERR_NOHINSTANCE
CDERR_LOADRESFAILURE	CDERR_NOHOOK
CDERR_LOADSTRFAILURE	CDERR_NOTEMPLATE
CDERR_LOCKRESFAILURE	CDERR_STRUCTSIZE
CDERR_MEMALLOCFAILURE	FRERR_BUFFERLENGTHZERO
Remarks

ReplaceText 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 the 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

CommDlgExtendedError, FINDREPLACE, IsDialogMessage, RegisterWindowMessage, WM_CTLCOLORDLG


ReplyMessage

The ReplyMessage function is used to reply to a message sent through the SendMessage function without returning control to the function that called SendMessage.

BOOL ReplyMessage(

LRESULT  lResult	// message-specific reply
);
Parameters

lResult

Specifies the result of the message processing. The possible values are based on the message sent.

Return Value

If the calling thread was processing a message sent from another thread or process, the return value is TRUE; otherwise, it is FALSE.

Remarks

By calling this function, the window procedure that receives the message allows the thread that called SendMessage to continue to run as though the thread receiving the message had returned control. The thread that calls the ReplyMessage function also continues to run.

If the message was not sent through SendMessage or if the message was sent by the same thread, ReplyMessage has no effect.

See Also

InSendMessage, SendMessage


ReportEvent

The ReportEvent function writes an entry at the end of the specified event log.

BOOL ReportEvent(

HANDLE  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 binary data, in bytes
LPCTSTR  *plpszStrings,	// array of strings to merge with message
LPVOID  lpvData	// address of binary data
);
Parameters

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

Return Value

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, call GetLastError.

Remarks

This function is used to log an event. The entry is written to the end of the configured logfile for the source identified by the 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, RegisterEventSource


ResetDC

The ResetDC function updates the given printer or plotter device context, based on the information in the specified structure.

HDC ResetDC(

HDC  hdc,	// handle of device context
CONST DEVMODE *  lpInitData	// address of structure with device context information
);
Parameters

hdc

Identifies the device context to update.

lpInitData

Points to a DEVMODE structure containing information about the new device context.

Return Value

If the function succeeds, the return value is the handle of the original device context.

If the function fails, the return value is NULL.

Remarks

An application will typically use the ResetDC function when a window receives a WM_DEVMODECHANGE message. ResetDC can also be used to change the paper orientation or paper bins while printing a document.

The ResetDC function cannot be used to change the driver name, device name, or the output port. When the user changes the port connection or device name, the application must delete the original device context and create a new device context with the new information.

An application can pass an information device context to the ResetDC function. In that situation, ResetDC will always return a printer device context.

See Also

DeviceCapabilities, DEVMODE, Escape


ResetDisplay
ResetDisplay  (preliminary−Windows 95)

The ResetDisplay function informs the system that the display resolution is to be changed. A Control Panel application calls this function after updating the registry.

BOOL API ResetDisplay(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

This function does the following:

1.	Broadcasts a WM_DISPLAYCHANGE message, with wParam = FALSE, indicating the display resolution is about to change.

2.	Changes the display resolution and updates various internal variables.

3.	Moves windows and icons that are no longer visible, if any.

4.	Invalidates the entire desktop to force a repainting.

5.	Broadcasts a WM_DISPLAYCHANGE message, with wParam = TRUE, indicating that the display resolution has changed.

The logical dots per inch and number of colors do not change.

See Also

WM_DISPLAYCHANGE


ResetEvent

The ResetEvent function sets the state of the specified event object to nonsignaled.

BOOL ResetEvent(

HANDLE  hEvent	// handle of event object
);
Parameters

hEvent

Identifies the event object. The CreateEvent or OpenEvent function returns this handle, which must have EVENT_MODIFY_STATE access.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The state of an event object remains nonsignaled until it is explicitly set to signaled by the SetEvent or PulseEvent function. This nonsignaled state blocks the execution of any threads that have specified the event object in a call to one of the wait functions.

The ResetEvent function is used primarily for manual-reset event objects, which must be set explicitly to the nonsignaled state. Auto-reset event objects automatically change from signaled to nonsignaled after a single waiting thread is released.

See Also

CreateEvent, OpenEvent, PulseEvent, SetEvent


ResetPrinter

The ResetPrinter function lets an application specify the data type and device mode values that are used for printing documents submitted by the StartDocPrinter function. These values can be overridden by using the SetJob function once document printing has started.

BOOL ResetPrinter (

HANDLE  hPrinter,	// printer handle
LPPRINTER_DEFAULTS  pDefault	// address of printer defaults structure
);
Parameters

hPrinter

Identifies a printer.

pDefault

Points to a PRINTER_DEFAULTS structure.

The ResetPrinter function ignores the DesiredAccess member of the PRINTER_DEFAULTS structure. Set that member to zero.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

OpenPrinter, PRINTER_DEFAULTS, StartDocPrinter, SetJob


ResizePalette

The ResizePalette function increases or decreases the size of a logical palette based on the specified value.

BOOL ResizePalette(

HPALETTE  hpal	// handle of logical palette
UINT  nEntries,	// number of entries in logical palette
);
Parameters

hpal

Identifies the palette to be changed.

nEntries

Specifies the number of entries in the palette after it has been resized.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

If an application calls ResizePalette to reduce the size of the palette, the entries remaining in the resized palette are unchanged. If the application calls ResizePalette to enlarge the palette, the additional palette entries are set to black (the red, green, and blue values are all 0) and their flags are set to zero.

See Also

GetDeviceCaps


RestoreDC

The RestoreDC function restores a device context (DC) to the specified state. The device context is restored by popping state information off a stack created by earlier calls to the SaveDC function.

BOOL RestoreDC(

HDC  hdc,	// handle of device context
int  nSavedDC	// specifies state to be restored
);
Parameters

hdc

Identifies the device context.

nSavedDC

Specifies the instance of the device context to be restored. If this parameter is positive, nSavedDC represents a specific instance of the device context to be restored. If this parameter is negative, nSavedDC represents an instance relative to the current device context. For example, −1 restores the most recently saved state.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The stack can contain the state information for several instances of the device context. If the state specified by the given parameter is not at the top of the stack, RestoreDC deletes all state information between the top of the stack and the specified instance.

See Also

SaveDC


ResumeThread

The ResumeThread function decrements a thread's suspend count. When the suspend count is decremented to zero, the execution of the thread is resumed.

DWORD ResumeThread(

HANDLE  hThread	// identifies thread to restart
);
Parameters

hThread

Specifies a handle for the thread to be restarted. The handle must have THREAD_SUSPEND_RESUME access to the thread.

Return Value

If the function succeeds, the return value is the thread's previous suspend count.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

The ResumeThread function checks the suspend count of the subject thread. If the suspend count is 0, the thread is not currently suspended. Otherwise, the subject thread's suspend count is decremented. If the resulting value is 0, then the execution of the subject thread is resumed.

If the return value is 0, the specified thread was not suspended. If the return value is 1, the specified thread was suspended but was restarted. If the return value is greater than 1, the specified thread is still suspended.

Note that while reporting debug events, all threads within the reporting process are frozen. Debuggers are expected to use the SuspendThread and ResumeThread functions to limit the set of threads that can execute within a process. By suspending all threads in a process except for the one reporting a debug event, it is possible to "single step" a single thread. The other threads are not released by a continue operation if they are suspended.

See Also

SuspendThread


ReuseDDElParam

The ReuseDDElParam function allows an application to reuse a packed DDE lParam parameter, rather than allocating a new packed lParam. Using this function reduces reallocations for applications that pass packed DDE messages.

LONG ReuseDDElParam(

LONG  lParam,	// posted lParam to be reused
UINT  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
);
Parameters

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.

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The return value must be posted as the lParam parameter of a DDE message; it must not be used for any other purpose. Once the return value is posted, the posting application need not perform any action to dispose of the lParam parameter.

Use ReuseDDElParam instead of FreeDDElParam if the lParam parameter will be reused in a responding message. ReuseDDElParam returns the lParam appropriate for reuse.

This function allocates or frees lParam parameters as needed, depending on the packing requirements of the incoming and outgoing messages. This reduces reallocations in passing DDE messages.

See Also

FreeDDElParam, PackDDElParam, UnpackDDElParam


RevertToSelf

The RevertToSelf function terminates the impersonation of a client application.

BOOL RevertToSelf(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

It is advisable for a process to call the RevertToSelf function after finishing any impersonation begun by using the DdeImpersonateClient, ImpersonateNamedPipeClient, or ImpersonateSelf function.

See Also

DdeImpersonateClient, ImpersonateNamedPipeClient, ImpersonateSelf


RoundRect

The RoundRect function draws a rectangle with rounded corners. The rectangle is outlined by using the current pen and filled by using the current brush.

BOOL RoundRect(

HDC  hdc,	// handle of device context
int  nLeftRect,	// x-coord. of bounding rectangle's upper-left corner
int  nTopRect,	// y-coord. of bounding rectangle's upper-left corner
int  nRightRect,	// x-coord. of bounding rectangle's lower-right corner
int  nBottomRect,	// y-coord. of bounding rectangle's lower-right corner
int  nWidth,	// width of ellipse used to draw rounded corners
int  nHeight	// height of ellipse used to draw rounded corners
);
Parameters

hdc

Identifies the device context.

nLeftRect

Specifies the x-coordinate of the upper-left corner of the rectangle.

nTopRect

Specifies the y-coordinate of the upper-left corner of the rectangle.

nRightRect

Specifies the x-coordinate of the lower-right corner of the rectangle.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the rectangle.

nWidth

Specifies the width of the ellipse used to draw the rounded corners.

nHeight

Specifies the height of the ellipse used to draw the rounded corners.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The current position is neither used nor updated by this function.

See Also

Rectangle


SaveDC

The SaveDC function saves the current state of the specified device context (DC) by copying data describing selected objects and graphic modes (such as the bitmap, brush, palette, font, pen, region, drawing mode, and mapping mode) to a context stack.

int SaveDC(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context to be saved.

Return Value

If the function succeeds, the return value identifies the saved device context.

If the function fails, the return value is zero.

Remarks

The SaveDC function can be used any number of times to save any number of instances of the device context's state.

A saved state can later be restored by using the RestoreDC function.

See Also

RestoreDC


ScaleViewportExt

The ScaleViewportExt function is not implemented in the Win32 API. Win32-based applications should use the ScaleViewportExtEx function.


ScaleViewportExtEx

The ScaleViewportExtEx function modifies the viewport for a device context (DC) by using the ratios formed by the specified multiplicands and divisors.

BOOL ScaleViewportExtEx(

HDC  hdc,	// handle of device context
int  Xnum,	// horizontal multiplicand
int  Xdenom,	// horizontal divisor
int  Ynum,	// vertical multiplicand
int  Ydenom,	// vertical divisor
LPSIZE  lpSize	// address of previous viewport extents
);
Parameters

hdc

Identifies the device context.

Xnum

Specifies the amount by which to multiply the current horizontal extent.

Xdenom

Specifies the amount by which to divide the current horizontal extent.

Ynum

Specifies the amount by which to multiply the current vertical extent.

Ydenom

Specifies the amount by which to divide the current vertical extent.

lpSize

Points to a SIZE structure. The previous viewport extents (in device units) are placed in this structure. If lpSize is NULL, nothing is returned.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The viewport extents are modified as follows:

    xNewVE = (xOldVE * Xnum) / Xdenom

    yNewVE = (yOldVE * Ynum) / Ydenom

See Also

GetViewportExtEx, SIZE


ScaleWindowExt

The ScaleWindowExt function is not implemented in the Win32 API. Win32-based applications should use the ScaleWindowExtEx function.


ScaleWindowExtEx

The ScaleWindowExtEx function modifies the window for a device context using the ratios formed by the specified multiplicands and divisors.

BOOL ScaleWindowExtEx(

HDC  hdc,	// handle of device context
int  Xnum,	// horizontal multiplicand
int  Xdenom,	// horizontal divisor
int  Ynum,	// vertical multiplicand
int  Ydenom,	// vertical divisor
LPSIZE  lpSize	// address of previous window extents
);
Parameters

hdc

Identifies the device context.

Xnum

Specifies the amount by which to multiply the current horizontal extent.

Xdenom

Specifies the amount by which to divide the current horizontal extent.

Ynum

Specifies the amount by which to multiply the current vertical extent.

Ydenom

Specifies the amount by which to divide the current vertical extent.

lpSize

Points to a SIZE structure. The previous window extents (in logical units) are placed in this structure. If lpSize is NULL, nothing is returned.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The window extents are modified as follows:

    xNewWE = (xOldWE * Xnum) / Xdenom

    yNewWE = (yOldWE * Ynum) / Ydenom

See Also

GetWindowExtEx, SIZE


ScheduleJob

The ScheduleJob function requests that the print spooler schedule a specified print job for printing.

BOOL ScheduleJob(

HANDLE  hPrinter,	// specifies printer for the print job
DWORD  dwJobID	// print job identifier
);
Parameters

hPrinter

Handle that specifies a printer for the print job. This must be a local printer that is configured as a spooled printer. If hPrinter is a handle to a remote printer connection, or if the printer is configured for direct printing, the ScheduleJob function fails.

hPrinter must be the same printer handle specifed in the call to AddJob that obtained the dwJobID print job identifer.

dwJobID

Specifies the print job to be scheduled. You obtain this print job identifer by calling the AddJob function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

You obtain a printer handle by calling the OpenPrinter function.

You must successfully call the AddJob function before calling the ScheduleJob function. AddJob obtains the print job identifer that you pass to ScheduleJob as dwJobID. Both calls must use the same value for hPrinter.

The ScheduleJob function checks for a valid spool file. If there is an invalid spool file, or if it is empty, ScheduleJob deletes both the spool file and the corresponding print job entry in the print spooler.

See Also

AddJob, OpenPrinter


ScreenSaverConfigureDialog

The ScreenSaverConfigureDialog function receives messages sent to a screen saver's configuration dialog box. A screen saver that allows user configuration must support this function.

BOOL ScreenSaverConfigureDialog(

HWND  hwndDlg,	// handle of dialog box
UINT  uMsg,	// message
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hwndDlg

Identifies the configuration dialog box.

uMsg

Specifies the message.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

If the function processes the message, the return value is TRUE; otherwise, it is FALSE, except in response to a WM_INITDIALOG message. In response to a WM_INITDIALOG message, ScreenSaverConfigureDialog should return FALSE if it calls the SetFocus function to set the keyboard focus to one of the controls in the dialog box. Otherwise, the function should return TRUE, in which case the system sets the keyboard focus to the first control in the dialog box that can be given the focus.

Remarks

The dialog box template for the configuration dialog box must have the DLG_SCRNSAVECONFIGURE identifier.

The dialog box procedure is used only if the application specifies the default window class (WC_DIALOG) for the dialog box. The application uses the default class if no explicit class is given in the dialog box template. Although the dialog box procedure is similar to a window procedure, it must not call the DefWindowProc function to process unwanted messages. Unwanted messages are processed internally by the default dialog box procedure.

The ScreenSaverConfigureDialog function must be exported by including it in the EXPORTS statement in the application's module-definition (.DEF) file.

See Also

DefWindowProc, RegisterDialogClasses, SetFocus


ScreenSaverProc

The ScreenSaverProc function receives messages sent to the specified screen saver window.

LONG ScreenSaverProc(

HWND  hwnd,	// handle of screen saver window
UINT  uMsg,	// message
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hwnd

Identifies the window.

uMsg

Specifies the message.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

The return value is the result of the message processing and depends on the message sent.

Remarks

A screen saver's ScreenSaverProc window procedure should use the DefScreenSaverProc function instead of the DefWindowProc function to provide default message processing. The DefScreenSaverProc function passes any messages that do not affect screen saver operations to DefWindowProc.

The ScreenSaverProc function must be exported by including it in the EXPORTS statement in the application's module-definition (.DEF) file.

See Also

DefScreenSaverProc, DefWindowProc


ScreenToClient

The ScreenToClient function converts the screen coordinates of a specified point on the screen to client coordinates.

BOOL ScreenToClient(

HWND  hwnd,	// window handle for source coordinates
LPPOINT  lpPoint	// address of structure containing coordinates
);
Parameters

hwnd

Identifies the window whose client area will be used for the conversion.

lpPoint

Points to a POINT structure that contains the screen coordinates to be converted.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The function uses the window identified by the hwnd parameter and the screen coordinates given in the POINT structure to compute client coordinates. It then replaces the screen coordinates with the client coordinates. The new coordinates are relative to the upper-left corner of the specified window's client area.

The ScreenToClient function assumes the specified point is in screen coordinates.

See Also

ClientToScreen, MapWindowPoints, POINT


ScrollConsoleScreenBuffer

The ScrollConsoleScreenBuffer function moves a block of data in a screen buffer. The effects of the move can be limited by specifying a clipping rectangle, so the contents of the screen buffer outside the clipping rectangle are unchanged.

BOOL ScrollConsoleScreenBuffer(

HANDLE  hConsoleOutput,	// handle of a console screen buffer
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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

ScrollConsoleScreenBuffer copies the contents of a rectangular region of a screen buffer, specified by the psrctSourceRect parameter, to another area of the screen buffer. The target rectangle has the same dimensions as the psrctSourceRect rectangle 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 rectangle and the target rectangle. For example, if the clipping rectangle does not include a region that would have been filled by the contents of 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). 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

CHAR_INFO, SetConsoleWindowInfo, SMALL_RECT


ScrollDC

The ScrollDC function scrolls a rectangle of bits horizontally and vertically.

BOOL ScrollDC(

HDC  hdc,	// handle of device context
int  dx,	// horizontal scroll units
int  dy,	// vertical scroll units
CONST RECT  *lprcScroll,	// address of structure for scrolling rectangle
CONST RECT  *lprcClip,	// address of structure for clipping rectangle
HRGN  hrgnUpdate,	// handle of scrolling region
LPRECT  lprcUpdate	// address of structure for update rectangle
);
Parameters

hdc

Identifies the device context that contains the bits to be scrolled.

dx

Specifies the amount, in device units, of horizontal scrolling. This parameter must be a negative value to scroll to the left.

dy

Specifies the amount, in device units, of vertical scrolling. This parameter must be a negative value to scroll up.

lprcScroll

Points to the RECT structure containing the coordinates of the scrolling rectangle.

lprcClip

Points to the RECT structure containing the coordinates of the clipping rectangle. Only device bits within the clipping rectangle are affected. Bits scrolled from the outside of the rectangle to the inside are painted; bits scrolled from the inside of the rectangle to the outside are not painted.

hrgnUpdate

Identifies the region uncovered by the scrolling process. ScrollDC defines this region; it is not necessarily a rectangle.

lprcUpdate

Points to the RECT structure that receives the coordinates of the rectangle bounding the scrolling update region. This is the largest rectangular area that requires repainting. When the function returns, the values in the structure are in client coordinates, regardless of the mapping mode for the specified device context. This allows applications to use the update region in a call to the InvalidateRgn function, if required.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the lprcUpdate parameter is NULL, Windows does not compute the update rectangle. If both the hrgnUpdate and lprcUpdate parameters are NULL, Windows does not compute the update region. If hrgnUpdate is not NULL, Windows proceeds as though it contains a valid handle of the region uncovered by the scrolling process (defined by ScrollDC).

When you must scroll the entire client area of a window, use the ScrollWindow function; otherwise, use ScrollDC.

See Also

InvalidateRgn, RECT, ScrollWindow


ScrollWindow

The ScrollWindow function scrolls the content of the specified window's client area. This function exists for backward compatibility. For new applications, use the ScrollWindowEx function.

BOOL ScrollWindow(

HWND  hwnd,	// handle of window to scroll
int  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
);
Parameters

hwnd

Identifies the window where the client area is to be scrolled.

dx

Specifies the amount, in device units, of horizontal scrolling. If the window being scrolled has the CS_OWNDC or CS_CLASSDC style, then this parameter uses logical units rather than device units. This parameter must be a negative value to scroll the content of the window to the left.

dy

Specifies the amount, in device units, of vertical scrolling. If the window being scrolled has the CS_OWNDC or CS_CLASSDC style, then this parameter uses logical units rather than device units. This parameter must be a negative value to scroll the content of the window up.

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the caret is in the window being scrolled, ScrollWindow automatically hides the caret to prevent it from being erased and then restores the caret after the scrolling is finished. The caret position is adjusted accordingly.

The area uncovered by ScrollWindow is not repainted, but it is combined into the window's update region. The application eventually receives a WM_PAINT message notifying it that the region must be repainted. To repaint the uncovered area at the same time the scrolling is in action, call the UpdateWindow function immediately after calling ScrollWindow.

If the 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

RECT, ScrollDC, ScrollWindowEx, UpdateWindow


ScrollWindowEx

The ScrollWindowEx function scrolls the content of the specified window's client area. This function is similar to the ScrollWindow function, but it has additional features.

int ScrollWindowEx(

HWND  hwnd,	// handle of window to scroll
int  dx,	// amount of horizontal scrolling
int  dy,	// amount of vertical scrolling
CONST RECT  *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
);
Parameters

hwnd

Identifies the window where the client area is to be scrolled.

dx

Specifies the amount, in device units, of horizontal scrolling. This parameter must be a negative value to scroll to the left.

dy

Specifies the amount, in device units, of vertical scrolling. This parameter must be a negative value to scroll up.

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.
Return Value

If the function succeeds, the return value is SIMPLEREGION (rectangular invalidated region), COMPLEXREGION (nonrectangular invalidated region; overlapping rectangles), or NULLREGION (no invalidated region).

If the function fails, the return value is ERROR.

Remarks

If the SW_INVALIDATE and SW_ERASE flags are not specified, ScrollWindowEx does not invalidate the area that is scrolled from. If either of these flags is set, ScrollWindowEx invalidates this area. The area is not updated until the application calls the UpdateWindow function, calls the RedrawWindow function (specifying the RDW_UPDATENOW or RDW_ERASENOW flag), or retrieves the WM_PAINT message from the application queue.

If the window has the WS_CLIPCHILDREN style, the returned areas specified by hrgnUpdate and lprcUpdate represent the total area of the scrolled window that must be updated, including any areas in child windows that need updating.

If the SW_SCROLLCHILDREN flag is specified, Windows does not properly update the screen if part of a child window is scrolled. The part of the scrolled child window that lies outside the source rectangle is not erased and is not properly redrawn in its new destination. To move child windows that do not lie completely within the rectangle specified by lprcScroll, 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 lprcScroll, lprcClip, lprcUpdate, and hrgnUpdate) are determined as client coordinates, regardless of whether the window has the CS_OWNDC or CS_CLASSDC class style. Use the LPtoDP and DPtoLP functions to convert to and from logical coordinates, if necessary.

See Also

DeferWindowPos, DPtoLP, LPtoDP, RECT, RedrawWindow, ScrollDC, ScrollWindow, UpdateWindow


SearchPath

The SearchPath function searches for the specified file.

DWORD SearchPath(

LPCTSTR  lpszPath,	// address of search path
LPCTSTR  lpszFile,	// address of filename
LPCTSTR  lpszExtension,	// address of extension
DWORD  cchReturnBuffer,	// size, in characters, of buffer
LPTSTR  lpszReturnBuffer,	// address of buffer for found filename
LPTSTR  *plpszFilePart	// address of pointer to file component
);
Parameters

lpszPath

Points to a null-terminated string that specifies the path to be searched for the file. If this parameter is NULL, the function searches for a matching file in the following directories in the following sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	Windows 95: The Windows system directory. Use the GetSystemDirectory function to get the path of this directory.

Windows NT: The 32-bit Windows system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.

4.	Windows NT only: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.

5.	The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.

6.	The directories that are listed in the PATH environment variable.

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 filename extension must be a period (.). The extension is added only if the specified filename does not end with an extension.

If a filename extension is not required or if the filename contains an extension, this parameter can be NULL.

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

Points to the address (within lpszReturnBuffer) of the last component of the valid path and filename, which is the address of the character immediately following the final backslash (\) in the path.

Return Value

If the function succeeds, the value returned is the length, in characters, of the string copied to the buffer, not including the terminating null character. If the return value is greater than cchReturnBuffer, the value returned is the size of the buffer required to hold the path.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

FindFirstFile, FindNextFile, GetSystemDirectory, GetWindowsDirectory


select

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

int select (

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

nfds

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

readfds

An optional pointer to a set of sockets to be checked for readability.

writefds

An optional pointer to a set of sockets to be checked for writability

exceptfds

An optional pointer to a set of sockets to be checked for errors.

timeout

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

Return Value

If the function succeeds, select returns the total number of descriptors that are ready and contained in the fd_set structures, or zero if the time limit expired.

If the function fails,a value of SOCKET_ERROR is returned. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINVAL	The timeout value is not valid.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAENOTSOCK	One of the descriptor sets contains an entry that is not a socket.
Remarks

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

The parameter readfds identifies those sockets that are to be checked for readability. If the socket is currently listening, it will be marked as readable if an incoming connection request has been received, so that an accept is guaranteed to complete without blocking. For other sockets, readability means that queued data is available for reading or, for sockets of type SOCK_STREAM, that the virtual socket corresponding to the socket has been closed, so that a recv or recvfrom is guaranteed to complete without blocking. If the virtual circuit was closed gracefully, then a recv will return immediately with zero bytes read; if the virtual circuit was reset, then a recv will complete immediately with the error code WSAECONNRESET. The presence of out-of-band data will be checked if the socket option SO_OOBINLINE has been enabled (see setsockopt).

The parameter writefds identifies those sockets that are to be checked for writeability. If a socket is connecting (nonblocking), writability means that the connection establishment successfully completed. If the socket is not in the process of connecting, writability means that a send or sendto will complete without blocking. [It is not specified how long this guarantee can be assumed to be valid, particularly in a multithreaded environment.]

The parameter exceptfds identifies those sockets that are to be checked for the presence of out-of-band data or any exceptional error conditions. Note that out-of-band data will only be reported in this way if the option SO_OOBINLINE is FALSE. For a SOCK_STREAM, the breaking of the connection by the peer or due to KEEPALIVE failure will be indicated as an exception. This specification does not define which other errors will be included. If a socket is connecting (nonblocking), failure of the connect attempt is indicated in exceptfds.

Any of readfds, writefds, or exceptfds may be given as NULL if no descriptors are of interest.

Four macros are defined in the header file WINSOCK.H for manipulating the descriptor sets. The variable FD_SETSIZE determines the maximum number of descriptors in a set. (The default value of FD_SETSIZE is 64, which may be modified by #defining FD_SETSIZE to another value before #including WINSOCK.H.) Internally, an fd_set is represented as an array of SOCKETs; the last valid entry is followed by an element set to INVALID_SOCKET. The macros are:

FD_CLR(s, *set)	Removes the descriptor s from set.
FD_ISSET(s, *set)	Nonzero if s is a member of the set, zero otherwise.
FD_SET(s, *set)	Adds descriptor s to set.
FD_ZERO(*set)	Initializes the set to the NULL set.
The parameter timeout controls how long the select may take to complete. If timeout is a null pointer, select will block indefinitely until at least one descriptor meets the specified criteria. Otherwise, timeout points to a timeval structure which specifies the maximum time that select should wait before returning. If the timeval is initialized to {0, 0}, select will return immediately; this is used to "poll" the state of the selected sockets. If this is the case, then the select call is considered nonblocking and the standard assumptions for nonblocking calls apply. For example, the blocking hook must not be called, and the Windows Sockets implementation must not yield.

See Also

accept, connect, recv, recvfrom, send, sendto, setsockopt, WSAAsyncSelect WSACancelBlockingCall, WSAStartup


SelectClipPath

The SelectClipPath function selects the current path as a clipping region for a device context, combining the new region with any existing clipping region by using the specified mode.

BOOL SelectClipPath(

HDC  hdc,	// handle of device context
int  iMode	// clipping mode
);
Parameters

hdc

Identifies the device context of the path.

iMode

Specifies the way to use the path. The following values are allowed:

Value	Meaning
RGN_AND	The new clipping region includes the intersection (overlapping areas) of the current clipping region and the current path.
RGN_COPY	The new clipping region is the current path.
RGN_DIFF	The new clipping region includes the areas of the current clipping region with those of the current path excluded.
RGN_OR	The new clipping region includes the union (combined areas) of the current clipping region and the current path.
RGN_XOR	The new clipping region includes the union of the current clipping region and the current path but without the overlapping areas.
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

The device context identified by the hdc parameter must contain a closed path.

See Also

BeginPath, EndPath


SelectClipRgn

The SelectClipRgn function selects a region as the current clipping region for the specified device context.

int SelectClipRgn(

HDC  hdc,	// handle of device context
HRGN  hrgn	// handle of region to be selected
);
Parameters

hdc

Identifies the device context.

hrgn

Identifies the region to be selected.

Return Value

If the function succeeds, the return value specifies the region's complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred. (The previous clipping region is unaffected.)
Remarks

Only a copy of the selected region is used. The region itself can be selected for any number of other device contexts or it can be deleted.

The SelectClipRgn function assumes that the coordinates for a region are specified in device units.

To remove a device-context's clipping region, specify a NULL region handle.

See Also

ExtSelectClipRgn


SelectObject

The SelectObject function selects an object into the specified device context. The new object replaces the previous object of the same type.

HGDIOBJ SelectObject(

HDC  hdc,	// handle of device context
HGDIOBJ  hgdiobj	// handle of object
);
Parameters

hdc

Identifies the device context.

hgdiobj

Identifies the object to be selected. The specified object must have been created by using one of the following functions:

Object	Functions
Bitmap	CreateBitmap, CreateBitmapIndirect, CreateCompatibleBitmap, CreateDIBitmap, CreateDIBSection
	(Bitmaps can be selected for memory device contexts only, and for only one device context at a time.)
Brush	CreateBrushIndirect, CreateDIBPatternBrush, CreateDIBPatternBrushPt, CreateHatchBrush, CreatePatternBrush, CreateSolidBrush
Font	CreateFont, CreateFontIndirect
Pen	CreatePen, CreatePenIndirect
Region	CombineRgn, CreateEllipticRgn, CreateEllipticRgnIndirect, CreatePolygonRgn, CreateRectRgn, CreateRectRgnIndirect
Return Value

If the selected object is not a region and the function succeeds, the return value is the handle of the object being replaced. If the selected object is a region and the function succeeds, the return value is one of the following values:

Value	Meaning
SIMPLEREGION	Region consists of a single rectangle.
COMPLEXREGION	Region consists of more than one rectangle.
NULLREGION	Region is empty.
If an error occurs and the selected object is not a region, the return value is NULL. Otherwise, it is GDI_ERROR.

Remarks

This function returns the previously selected object of the specified type. An application should always replace a new object with the original, default object after it has finished drawing with the new object.

An application cannot select a bitmap into more than one device context at a time.

See Also

CombineRgn, CreateBitmap, CreateBitmapIndirect, CreateBrushIndirect, CreateCompatibleBitmap, CreateDIBitmap, CreateDIBPatternBrush, CreateEllipticRgn, CreateEllipticRgnIndirect, CreateFont, CreateFontIndirect, CreateHatchBrush, CreatePatternBrush, CreatePen, CreatePenIndirect, CreatePolygonRgn, CreateRectRgn, CreateRectRgnIndirect, CreateSolidBrush, SelectClipRgn, SelectPalette


SelectPalette

The SelectPalette function selects the specified logical palette into a device context.

HPALETTE SelectPalette(

HDC  hdc,	// handle of device context
HPALETTE  hpal,	// handle of logical color palette
BOOL  bForceBackground	// foreground/background mode
);
Parameters

hdc

Identifies the device context.

hpal

Identifies the logical palette to be selected.

bForceBackground

Specifies whether the logical palette is forced to be a background palette. If this value is TRUE, the RealizePalette function causes the logical palette to be mapped to the colors already in the physical palette in the best possible way. This is always done, even if the window for which the palette is realized belongs to a thread without active focus.

If this value is FALSE, RealizePalette causes the logical palette to be copied into the device palette when the application is in the foreground. (If the hdc parameter is a memory device context, this parameter is ignored.)

Return Value

If the function succeeds, the return value identifies the device context's previous logical palette.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

An application can select a logical palette into more than one device context. However, changes to a logical palette will affect all device contexts for which it is selected.

An application might call the SelectPalette function with the bForceBackground parameter set to TRUE if the child windows of a top-level window each realize their own palettes. However, only the child window that needs to realize its palette must set bForceBackground to TRUE; other child windows must set this value to FALSE.

See Also

CreatePalette, GetDeviceCaps, RealizePalette


send

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

int send (

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

s

A descriptor identifying a connected socket.

buf

A buffer containing the data to be transmitted.

len

The length of the data in buf.

flags

Specifies the way the call is made.

Return Value

If the function succeeds, send returns the total number of characters sent. (Note that this may be less than the number indicated by len.)

If the function fails, a value of SOCKET_ERROR is returned. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEACCES	The requested address is a broadcast address, but the appropriate flag was not set.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEFAULT	The buf argument is not in a valid part of the user address space.
WSAENETRESET	The connection must be reset because the Windows Sockets implementation dropped it.
WSAENOBUFS	The Windows Sockets implementation reports a buffer deadlock.
WSAENOTCONN	The socket is not connected.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not of type SOCK_STREAM.
WSAESHUTDOWN	The socket has been shutdown; it is not possible to send on a socket after shutdown has been invoked with how set to 1 or 2.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the requested operation would block.
WSAEMSGSIZE	The socket is of type SOCK_DGRAM, and the datagram is larger than the maximum supported by the Windows Sockets implementation.
WSAEINVAL	The socket has not been bound with bind.
WSAECONNABORTED	The virtual circuit was aborted due to timeout or other failure.
WSAECONNRESET	The virtual circuit was reset by the remote side.
Remarks

The send function is used on connected datagram or stream sockets and is used to write outgoing data on a socket. For datagram sockets, care must be taken not to exceed the maximum IP packet size of the underlying subnets, which is given by the iMaxUdpDg element in the WSAData structure returned by WSAStartup. If the data is too long to pass atomically through the underlying protocol the error WSAEMSGSIZE is returned, and no data is transmitted.

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

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

The flags parameter may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by using a bitwise OR operation with any of the following values:

Value	Meaning
MSG_DONTROUTE	Specifies that the data should not be subject to routing. A Windows Sockets supplier may choose to ignore this flag.
MSG_OOB	Send out-of-band data (SOCK_STREAM only)
See Also

bind, recv, recvfrom, socket, select, sendto, shutdown, WSACancelBlockingCall, WSAStartup,


SendAsyncProc

A SendAsyncProc function is an application-defined callback function that the operating system calls when the SendMessageCallback function is called. The system passes the message to the callback function after passing the message to the destination window procedure. A value of type SENDASYNCPROC is a pointer to such a function.

VOID CALLBACK SendAsyncProc(

HWND  hwnd,	// handle of destination window
UINT  uMsg,	// message
DWORD  dwData,	// application-defined value
LRESULT  lResult	// result of message processing
);
Parameters

hwnd

Identifies the window whose window procedure received the message.

If the SendMessageCallback function was called with its hwnd parameter set to HWND_BROADCAST, the operating system calls the SendAsyncProc function once for each top-level window.

uMsg

Specifies the message.

dwData

Specifies an application-defined value sent from the SendMessageCallback function.

lResult

Specifies the result of the message processing and depends on the message.

Return Value

This callback function does not return a value.

Remarks

SendAsyncProc is a placeholder for an application-defined function name.

You install a SendAsyncProc application-defined callback function by passing a SENDASYNCPROC pointer to the SendMessageCallback function.

See Also

SendMessage, SendMessageCallback


SendDlgItemMessage

The SendDlgItemMessage function sends a message to the specified control in a dialog box.

LONG SendDlgItemMessage(

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
);
Parameters

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-specific information.

lParam

Specifies additional message-specific information.

Return Value

The return value specifies the result of the message processing and depends on the message sent.

Remarks

The SendDlgItemMessage function does not return until the message has been processed.

Using SendDlgItemMessage is identical to retrieving a handle of the specified control and calling the SendMessage function.

See Also

SendMessage


SendMessage

The SendMessage function sends the specified message to a window or windows. The function calls the window procedure for the specified window and does not return until the window procedure has processed the message. The PostMessage function, in contrast, posts a message to a thread's message queue and returns immediately.

LRESULT SendMessage(

HWND  hwnd,	// handle of destination window
UINT  uMsg,	// message to send
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hwnd

Identifies the window whose window procedure will receive the message. If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows.

uMsg

Specifies the message to be sent.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

The return value specifies the result of the message processing and depends on the message sent.

Remarks

If the specified window was created by the calling thread, the window procedure is called immediately as a subroutine. If the specified window was created by a different thread, Windows switches to that thread and calls the appropriate window procedure.

See Also

InSendMessage, PostMessage, SendDlgItemMessage


SendMessageCallback

The SendMessageCallback function sends the specified message to a window or windows. The function calls the window procedure for the specified window and returns immediately. After the window procedure processes the message, the system calls the specified callback function, passing the result of the message processing and an application-defined value to the callback function.

BOOL SendMessageCallback(

HWND  hwnd,	// handle of destination window
UINT  uMsg,	// message to send
WPARAM  wParam,	// first message parameter
PARAM  lParam,	// second message parameter
SENDASYNCPROC  lpResultCallBack,	// function to receive message value
DWORD  dwData	// value to pass to callback function
);
Parameters

hwnd

Identifies the window whose window procedure will receive the message. If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows.

uMsg

Specifies the message to be sent.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

lpResultCallBack

Points to a callback function that the system calls after the window procedure processes the message. See SendAsyncProc for information on suitable callback functions.

If  hwnd is HWND_BROADCAST, the operating system calls the SendAsyncProc callback function once for each top-level window.

dwData

Specifies an application-defined value to be sent to the callback function pointed to by the lpfnResultCallBack parameter.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

InSendMessage, PostMessage, SendAsyncProc, SendDlgItemMessage, SendMessage, SendMessageTimeout, SendNotifyMessage


SendMessageTimeout

The SendMessageTimeout function sends the specified message to a window or windows. The function calls the window procedure for the specified window and, if the specified window belongs to a different thread, does not return until the window procedure has processed the message or the specified time-out period has elapsed. If the window receiving the message belongs to the same queue as the current thread, the window procedure is called directly—the time-out value is ignored.

LRESULT SendMessageTimeout(

HWND  hwnd,	// handle of destination window
UINT  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
);
Parameters

hwnd

Identifies the window whose window procedure will receive the message. If this parameter is HWND_TOPMOST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows.

uMsg

Specifies the message to be sent.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

fuFlags

Specifies how to send the message. This parameter can be a combination of the following values:

Value	Meaning
SMTO_ABORTIFHUNG	Returns without waiting for the time-out period to elapse if the receiving process appears to be in a "hung" state.
SMTO_BLOCK	Prevents the calling thread from processing any other requests until the function returns.
SMTO_NORMAL	The calling thread is not prevented from processing other requests while waiting for the function to return.
uTimeout

Specifies the duration, in milliseconds, of the time-out period.

lpdwResult

Specifies the result of the message processing and depends on the message sent.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

InSendMessage, PostMessage, SendDlgItemMessage, SendMessage, SendMessageCallback, SendNotifyMessage


SendNotifyMessage

The SendNotifyMessage function sends the specified message to a window. If the window was created by the calling thread, SendNotifyMessage calls the window procedure for the window and does not return until the window procedure has processed the message. If the window was created by a different thread, SendNotifyMessage passes the message to the window procedure and returns immediately; it does not wait for the window procedure to finish processing the message.

BOOL SendNotifyMessage(

HWND  hwnd,	// handle of destination window
UINT  uMsg,	// message to send
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hwnd

Identifies the window whose window procedure will receive the message. If this parameter is HWND_BROADCAST, the message is sent to all top-level windows in the system, including disabled or invisible unowned windows, overlapped windows, and pop-up windows; but the message is not sent to child windows.

uMsg

Specifies the message to be sent.

wParam

Specifies additional message-specific information.

lParam

Specifies additional message-specific information.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

PostMessage, PostThreadMessage, SendMessage


sendto

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

int sendto (

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

s

A descriptor identifying a socket.

buf

A buffer containing the data to be transmitted.

len

The length of the data in buf.

flags

Specifies the way in which the call is made.

to

An optional pointer to the address of the target socket.

tolen

The size of the address in to.

Return Value

If the function succeeds, sendto returns the total number of characters sent. (Note that this may be less than the number indicated by len.)

If the function fails, a value of SOCKET_ERROR is returned. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEACCES	The requested address is a broadcast address, but the appropriate flag was not set.
WSAEINTR	The (blocking) call was canceled using WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEFAULT	The buf or to parameters are not part of the user address space, or the to argument is too small (less than the size of a socket address structure).
WSAENETRESET	The connection must be reset because the Windows Sockets implementation dropped it.
WSAENOBUFS	The Windows Sockets implementation reports a buffer deadlock.
WSAENOTCONN	The socket is not connected (SOCK_STREAM only).
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not of type SOCK_STREAM.
WSAESHUTDOWN	The socket has been shut down; it is not possible to sendto on a socket after shutdown has been invoked with how set to 1 or 2.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the requested operation would block.
WSAEMSGSIZE	The socket is of type SOCK_DGRAM, and the datagram is larger than the maximum supported by the Windows Sockets implementation.
WSAECONNABORTED	The virtual circuit was aborted due to timeout or other failure.
WSAECONNRESET	The virtual circuit was reset by the remote side.
WSAEADDRNOTAVAIL	The specified address is not available from the local computer.
WSAEAFNOSUPPORT	Addresses in the specified family cannot be used with this socket.
WSAEDESTADDRREQ	A destination address is required.
WSAENETUNREACH	The network can't be reached from this host at this time.
Remarks

The sendto function is used on datagram or stream sockets and is used to write outgoing data on a socket. For datagram sockets, care must be taken not to exceed the maximum IP packet size of the underlying subnets, which is given by the iMaxUdpDg element in the WSAData structure returned by WSAStartup. If the data is too long to pass atomically through the underlying protocol, the error WSAEMSGSIZE is returned, and no data is transmitted.

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

The sendto function is normally used on a SOCK_DGRAM socket to send a datagram to a specific peer socket identified by the to parameter. On a SOCK_STREAM socket, the to and tolen parameters are ignored; in this case the sendto is equivalent to send.

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

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

The flags parameter can be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by using a bitwise OR operation with any of the following values:

Value	Meaning
MSG_DONTROUTE	Specifies that the data should not be subject to routing. A Windows Sockets supplier may choose to ignore this flag.
MSG_OOB	Send out-of-band data (SOCK_STREAM only).
See Also

recv, recvfrom, socket, select, send, shutdown, WSACancelBlockingCall, WSAStartup,


ServiceMain

A ServiceMain function is a function that a service process specifies as the entry point function of a particular service. The function can have any application-defined name.

VOID ServiceMain(

DWORD  dwArgc,	// number of arguments
LPTSTR  *lpszArgv	// address of array of argument string pointers
);
Parameters

dwArgc

Specifies the number of arguments in the lpszArgv array.

lpszArgv

Points to an array of pointers that point to null-terminated argument strings. The first argument in the array is the name of the service, and subsequent arguments are any strings passed to the service by the process that called the StartService function to start the service.

Return Value

This function does not return a value.

Remarks

A service process can start one or more services. For each service that it can start, a service process has a SERVICE_TABLE_ENTRY structure that specifies the service name and a pointer to the ServiceMain function for that service.

When the service control manager receives a request to start a service, it starts the service process (if it is not already running). The main thread of the service process calls the StartServiceCtrlDispatcher function with a pointer to an array of SERVICE_TABLE_ENTRY structures. Then the service control manager sends a start request to the service control dispatcher for this service process. The service control dispatcher creates a new thread to execute the ServiceMain function of the service being started.

This function should immediately call the RegisterServiceCtrlHandler function to specify a Handler function to handle control requests. Next, it should call the SetServiceStatus function to send status information to the service control manager. After these calls, the function completes the initialization tasks of the service, and then it waits for the service to terminate.

A ServiceMain function does not return until the service is ready to terminate.

See Also

Handler, RegisterServiceCtrlHandler, SetServiceStatus, SERVICE_TABLE_ENTRY, StartServiceCtrlDispatcher


SetAbortProc

The SetAbortProc function sets the application-defined abort function that allows a print job to be canceled during spooling. This function replaces the SETABORTPROC printer escape.

int SetAbortProc(

HDC  hdc,	// handle of device context
ABORTPROC  lpAbortProc	// address of abort function
);
Parameters

hdc

Identifies the device context for the print job.

lpAbortProc

Points to the application-defined abort function. For more information about the callback function, see the AbortProc callback function.

Return Value

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is SP_ERROR. To get extended error information, call GetLastError.

See Also

AbortDoc, AbortProc


SetAclInformation

The SetAclInformation function sets information about an access-control list (ACL).

BOOL SetAclInformation(

PACL  pAcl,	// address of access-control list
LPVOID  lpvAclInfo,	// address of ACL information
DWORD  cbAclInfo,	// size of ACL information
ACL_INFORMATION_CLASS  aclic	// specifies class of requested info
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

ACL, ACL_INFORMATION_CLASS, ACL_REVISION_INFORMATION, GetAclInformation, InitializeAcl, IsValidAcl


SetActiveWindow

The SetActiveWindow function makes the specified top-level window associated with the thread calling this function the active window.

HWND SetActiveWindow(

HWND  hwnd	// handle of window to activate
);
Parameters

hwnd

Identifies the top-level window to be activated.

Return Value

If the function succeeds, the return value is the handle of the window that was previously active.

Remarks

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.

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 call to SetActiveWindow.

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


SetArcDirection

The SetArcDirection sets the drawing direction to be used for arc and rectangle functions.

int SetArcDirection(

HDC  hdc,	// identifies the device context
int  ArcDirection	// specifies the new arc direction
);
Parameters

hdc

Identifies the device context.

ArcDirection

Specifies the new arc direction. This parameter can be one of the following values:

Value	Meaning
AD_COUNTERCLOCKWISE	Figures drawn counterclockwise.
AD_CLOCKWISE	Figures drawn clockwise.
Return Value

If the function succeeds, the return value specifies the old arc direction.

If the function fails, the return value is zero.

Remarks

The default direction is counterclockwise.

The SetArcDirection function specifies the direction in which the following functions draw:

Arc	ArcTo
Chord	Ellipse
Pie	Rectangle
RoundRect


SetBitmapBits

The SetBitmapBits function sets the bits of color data for a bitmap to the specified values.

The SetBitmapBits function is included only for compatibility with earlier versions of Windows. For Win32-based applications, use the SetDIBits function.

LONG SetBitmapBits(

HBITMAP  hbmp,	// handle of bitmap
DWORD  cBytes,	// number of bytes in bitmap array
CONST VOID  *lpBits	// address of array with bitmap bits
);
Parameters

hbmp

Identifies the bitmap to be set.

cBytes

Specifies the number of bytes pointed to by the lpBits parameter.

lpBits

Points to an array of bytes that contain color data for the specified bitmap.

Return Value

If the function succeeds, the return value is the number of bytes used in setting the bitmap bits.

If the function fails, the return value is zero.

Remarks

The array identified by lpBits must be WORD aligned.

See Also

GetBitmapBits, SetDIBits


SetBitmapDimension

The SetBitmapDimension function has been deleted. Win32-based applications should use the SetBitmapDimensionEx function.


SetBitmapDimensionEx

The SetBitmapDimensionEx function assigns preferred dimensions to a bitmap. These dimensions can be used by applications; however, they are not used by Windows.

BOOL SetBitmapDimensionEx(

HBITMAP  hBitmap,	// handle of bitmap
int  nWidth,	// bitmap width in .01-mm units
int  nHeight,	// bitmap height in .01-mm units
LPSIZE  lpSize	// address of structure for original dimensions
);
Parameters

hBitmap

Identifies the bitmap.  The bitmap cannot be a DIB section bitmap.

nWidth

Specifies the width, in 0.1-millimeter units, of the bitmap.

nHeight

Specifies the height, in 0.1-millimeter units, of the bitmap.

lpSize

Points to a SIZE structure to receive the previous dimensions of the bitmap. This pointer can be NULL.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application can retrieve the dimensions assigned to a bitmap with the SetBitmapDimensionEx function by calling the GetBitmapDimensionEx function.

The bitmap identified by hBitmap cannot be a dib section, which is a bitmap created by the CreateDIBSection function. If the bitmap is a dib section, the SetBitmapDimensionEx function fails.

See Also

CreateDIBSection, GetBitmapDimensionEx, SIZE


SetBkColor

The SetBkColor function sets the current background color to the specified color value, or to the nearest physical color if the device cannot represent the specified color value.

COLORREF SetBkColor(

HDC  hdc,	// handle of device context
COLORREF  crColor	// background color value
);
Parameters

hdc

Identifies the device context.

crColor

Specifies the new background color.

Return Value

If the function succeeds, the return value specifies the previous background color as a COLORREF value.

If the function fails, the return value is CLR_INVALID.

Remarks

This function fills the gaps between styled lines drawn using a pen created by the CreatePen function; it does not fill the gaps between styled lines drawn using a pen created by the ExtCreatePen function.

If the background mode is OPAQUE, the background color is used to fill gaps between styled lines, gaps between hatched lines in brushes, and character cells. The background color is also used when converting bitmaps from color to monochrome and vice versa.

See Also

CreatePen, GetBkMode, SetBkMode, COLORREF, ExtCreatePen


SetBkMode

The SetBkMode function sets the background mix mode of the specified device context. The background mix mode is used with text, hatched brushes, and pen styles that are not solid lines.

int SetBkMode(

HDC  hdc,	// handle of device context
int  iBkMode	// flag specifying background mode
);
Parameters

hdc

Identifies the device context.

iBkMode

Specifies the background mode. This parameter can be either of the following values:

Value	Description
OPAQUE	Background is filled with the current background color before the text, hatched brush, or pen is drawn.
TRANSPARENT	Background remains untouched.
Return Value

If the function succeeds, the return value specifies the previous background mode.

If the function fails, the return value is zero.

Remarks

The SetBkMode function affects the line styles for lines drawn using a pen created by the CreatePen function. SetBkMode does not affect lines drawn using a pen created by the ExtCreatePen function.

The iBkMode parameter can also be set to driver-specific values. GDI passes such values to the device driver and otherwise ignores them.

See Also

CreatePen, ExtCreatePen, GetBkMode


SetBoundsRect

The SetBoundsRect function controls the accumulation of bounding rectangle information for the specified device context. Windows can maintain a bounding rectangle for all drawing operations. An application can examine and set this rectangle. The drawing boundaries are useful for invalidating bitmap caches.

UINT SetBoundsRect(

HDC  hdc,	// handle of device context
CONST RECT  *lprcBounds,	// address of rectangle coordinates
UINT  flags	// controls rectangle combination
);
Parameters

hdc

Identifies the device context for which to accumulate bounding rectangles.

lprcBounds

Points to a RECT structure used to set the bounding rectangle. Rectangle dimensions are in logical coordinates. This parameter can be NULL.

flags

Specifies how the new rectangle will be combined with the accumulated rectangle. This parameter can be a combination of the following values:

Value	Description
DCB_ACCUMULATE	Adds the rectangle specified by the lprcBounds parameter to the bounding rectangle (using a rectangle union operation). Using both DCB_RESET and DCB_ACCUMULATE sets the bounding rectangle to the rectangle specified by the lprcBounds parameter.
DCB_DISABLE	Turns off boundary accumulation.
DCB_ENABLE	Turns on boundary accumulation, which is disabled by default.
DCB_RESET	Clears the bounding rectangle.
Return Value

If the function succeeds, the return value specifies the previous state of the bounding rectangle. This state can be a combination of the following values:

Value	Meaning
DCB_DISABLE	Boundary accumulation is off.
DCB_ENABLE	Boundary accumulation is on. DCB_ENABLE and DCB_DISABLE are mutually exclusive.
DCB_RESET	Bounding rectangle is empty.
DCB_SET	Bounding rectangle is not empty. DCB_SET and DCB_RESET are mutually exclusive.
Remarks

The DCB_SET value is a combination of the bit values DCB_ACCUMULATE and DCB_RESET. Applications that check the DCB_RESET bit to determine whether the bounding rectangle is empty must also check the DCB_ACCUMULATE bit. The bounding rectangle is empty only if the DCB_RESET bit is 1 and the DCB_ACCUMULATE bit is 0.

See Also

GetBoundsRect, RECT


SetBrushOrg

The SetBrushOrg function is not implemented in the Win32 API. Win32-based applications should use the SetBrushOrgEx function.


SetBrushOrgEx

The SetBrushOrgEx function sets the brush origin that GDI assigns to the next brush an application selects into the specified device context. The function supersedes the SetBrushOrg function.

BOOL SetBrushOrgEx(

HDC  hdc,	// handle of device context
int  nXOrg,	// x-coordinate of new origin
int  nYOrg,	// y-coordinate of new origin
LPPOINT  lppt	// points to previous brush origin
);
Parameters

hdc

Identifies the device context.

nXOrg

Specifies the x-coordinate, in device units, of the new brush origin. 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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A brush is a bitmap that the operating system uses to paint the interiors of filled shapes.

The brush origin is a pair of coordinates 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; the value 7 corresponds to the lowermost row.

When the operating system positions the brush at the start of any painting operation, it maps the origin of the brush to the location on the window's client area specified by the brush origin. For example, if the brush origin is (2,3), the operating system maps the origin of the brush, (0,0), to the location (2,3) on the window's client area.

The operating system automatically tracks the origin of all window-managed device contexts and adjusts their brushes as necessary to maintain an alignment of patterns on the surface. The brush origin that is set with this call is relative to the upper-left corner of the client area.

An application should call SetBrushOrgEx after setting the bitmap stretching mode to HALFTONE via SetStretchBltMode. This must be done to avoid brush misalignment.

See Also

GetBrushOrgEx, POINT, SetStretchBltMode


SetCapture

The SetCapture function sets the mouse capture to the specified window belonging to the current thread. Once a window has captured the mouse, all mouse input is directed to that window, regardless of whether the cursor is within the borders of that window. Only one window at a time can capture the mouse.

If the mouse cursor is over a window created by another thread, the system will direct mouse input to the specified window only if a mouse button is down.

HWND SetCapture(

HWND  hwnd	// handle of window to receive mouse capture
);
Parameters

hwnd

Identifies the window in the current thread that is to capture the mouse.

Return Value

If the function succeeds, the return value is the handle of the window that had previously captured the mouse. If there is no such window, the return value is NULL.

Remarks

Only the foreground window can capture the mouse. When a background window attempts to do so, the window receives messages only for mouse events that occur when the cursor hot spot is within the visible portion of the window. Also, even if the foreground window has captured the mouse, the user can still click another window, bringing it to the foreground.

When the window no longer requires all mouse input, the thread that created the window should call the ReleaseCapture function to release the mouse.

This function cannot be used to capture mouse input meant for another process.

Windows 95 only: Calling this function causes the window that is losing the mouse capture to receive a WM_CAPTURECHANGED message.

See Also

GetCapture, ReleaseCapture


SetCaretBlinkTime

The SetCaretBlinkTime function sets the caret blink time to the specified number of milliseconds. The blink time is the elapsed time, in milliseconds, required to invert the caret's pixels.

BOOL SetCaretBlinkTime(

UINT  wMSeconds	// blink time, in milliseconds
);
Parameters

wMSeconds

Specifies the new blink time, in milliseconds.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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

The SetCaretPos function moves the caret to the specified coordinates. If the window that owns the caret was created with the CS_OWNDC class style, then the specified coordinates are subject to the mapping mode of the device context associated with that window.

BOOL SetCaretPos(

int  nX,	// horizontal position
int  nY	// vertical position
);
Parameters

nX

Specifies the new x-coordinate of the caret.

nY

Specifies the new y-coordinate of the caret.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

SetCaretPos moves the caret whether or not the caret is hidden.

The caret is a shared resource; there is only one caret in the system. A window can set the caret position only if it owns the caret.

See Also

GetCaretPos, HideCaret, ShowCaret


SetClassLong

The SetClassLong function replaces the specified 32-bit (long) value at the specified offset into the extra class memory or the WNDCLASS structure for the class to which the specified window belongs.

DWORD SetClassLong(

HWND  hwnd,	// handle of window
int  nIndex,	// index of value to change
LONG  lNewVal	// new value
);
Parameters

hwnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the 32-bit value to replace. To set a 32-bit value in the extra class memory, specify the positive, zero-based byte offset of the value to be set. Valid values are in the range zero through the number of bytes of extra class memory, minus four; for example, if you specified 12 or more bytes of extra class memory, a value of 8 would be an index to the third 32-bit integer. To set any other value from the WNDCLASS structure, specify one of the following values:

Value	Action
GCL_CBCLSEXTRA	Sets the size, in bytes, of the extra memory associated with the class. Setting this value does not change the number of extra bytes already allocated.
GCL_CBWNDEXTRA	Sets the size, in bytes, of the extra window memory associated with each window in the class. Setting this value does not change the number of extra bytes already allocated. For information on how to access this memory, see SetWindowLong and SetWindowWord.
GCL_HBRBACKGROUND	Replaces the handle of the background brush associated with the class.
GCL_HCURSOR	Replaces the handle of the cursor associated with the class.
GCL_HICON	Replaces the handle of the icon associated with the class.
GCL_HMODULE	Replaces the handle of the module that registered the class.
GCL_MENUNAME	Replaces the address of the menu name string. The string identifies the menu resource associated with the class.
GCL_STYLE	Replaces the window-class style bits.
GCL_WNDPROC	Replaces the address of the window procedure associated with the class.
lNewVal

Specifies the replacement value.

Return Value

If the function succeeds, the return value is the previous value of the specified 32-bit integer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If you use the SetClassLong function and the GCL_WNDPROC index to replace the window procedure, the window procedure must conform to the guidelines specified in the description of the WindowProc callback function.

Calling SetClassLong with the GCL_WNDPROC index creates a subclass of the window class that affects all windows subsequently created with the class. An application should not subclass a window created by another process.

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

Use the SetClassLong function with care. For example, it is possible to change the background color for a class by using SetClassLong, but this change does not immediately repaint all windows belonging to the class.

See Also

GetClassLong, GetClassWord, RegisterClass, SetClassWord, SetWindowLong, SetWindowWord, WindowProc, WNDCLASS


SetClassWord

The SetClassWord function replaces the 16-bit (word) value at the specified offset into the extra class memory for the window class to which the specified window belongs.

WORD SetClassWord(

HWND  hwnd,	// handle of window
int  nIndex,	// index of value to change
WORD  wNewWord	// new value
);
Parameters

hwnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based byte offset of the value to be replaced. Valid values are in the range zero through the number of bytes of class memory minus two; for example, if you specified 10 or more bytes of extra class memory, a value of 8 would be an index to the fifth 16-bit integer.

wNewWord

Specifies the replacement value.

Return Value

If the function succeeds, the return value is the previous value of the specified 16-bit integer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra class memory by specifying a nonzero value in the cbClsExtra member of the WNDCLASS structure used with the RegisterClass function.

The GCW_ values are obsolete in the Win32 API. You must use the SetClassLong function to set the class values previously set by using the GCW_ values with the SetClassWord function.

See Also

GetClassLong, GetClassWord, RegisterClass, SetClassLong, WNDCLASS


SetClipboardData

The SetClipboardData function places data on the clipboard in a specified clipboard format. The window must be the current clipboard owner, and the application must have called the OpenClipboard function. (When responding to the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages, the clipboard owner must not call OpenClipboard before calling SetClipboardData.)

HANDLE SetClipboardData(

UINT  uFormat,	// clipboard format
HANDLE  hData	// data handle
);
Parameters

uFormat

Specifies a clipboard format. This parameter can be a registered format or any of the standard clipboard formats listed in the following Remarks section. For information about registered clipboard formats, see the RegisterClipboardFormat function.

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) upon request. If a window delays rendering, it must process the WM_RENDERFORMAT and WM_RENDERALLFORMATS messages.

Once SetClipboardData is called, the system owns the object identified by the hData parameter. The application can read the data, but must not free the handle or leave it locked. If the hData parameter identifies a memory object, the object must have been allocated using the GlobalAlloc function with the GMEM_MOVEABLE and GMEM_DDESHARE flags.

Return Value

If the function succeeds, the return value is the handle of the data.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The uFormat parameter can identify a registered clipboard format, or it can be one of the following values:

Value	Meaning
CF_BITMAP	A handle to a bitmap (HBITMAP).
CF_DIB	A memory object containing a BITMAPINFO structure followed by the bitmap bits.
CF_DIF	Software Arts' Data Interchange Format.
CF_DSPBITMAP	Bitmap display format associated with a private format. The 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_GDIOBJFIRST through CF_GDIOBJLAST	Windows 95 only: Range of integer values for application-defined GDI object clipboard formats. Handles associated with clipboard formats in this range are not automatically deleted using the GlobalFree function when the clipboard is emptied. Also, when using values in this range, the hData parameter is not a handle to a GDI object, but is a handle allocated by the GlobalAlloc function with the GMEM_DDESHARE and GMEM_MOVEABLE flags.
CF_HDROP	Windows 95 only: A handle of type HDROP that identifies a list of files. To retrieve the corresponding filenames, use the DragQueryDropFileInfo function.
CF_LOCALE	Windows 95: A 32-bit value that contains the locale identifier associated with text in the clipboard. The system automatically places this format in the clipboard whenever an application places data having the CF_TEXT format. This means applications can determine which character set was used to generate the text before attempting to paste the text into documents. Note that the clipboard does not support plain text in multiple character sets. To achieve this, use a fomatted text data type such as RTF instead.
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 on the clipboard as well.
	If the clipboard contains data in the CF_PALETTE (logical color palette) format, the application should use the SelectPalette and RealizePalette functions to realize (compare) any other data in the clipboard against that logical palette.
	When displaying clipboard data, Windows clipboard always uses as its current palette any object on the clipboard that is in the CF_PALETTE format.
CF_PENDATA	Data for the pen extensions to the Microsoft® Windows™ for Pen Computing.
CF_PRIVATEFIRST through CF_PRIVATELAST	Range of integer values for private clipboard formats. Handles associated with private clipboard formats are not freed automatically; the clipboard owner must free such handles, typically in response to the WM_DESTROYCLIPBOARD message.
CF_RIFF	Represents audio data more complex than can be represented in a CF_WAVE standard wave format.
CF_SYLK	Microsoft Symbolic Link (SYLK) format.
CF_TEXT	Text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data. Use this format for ANSI text.
CF_WAVE	Represents audio data in one of the standard wave formats, such as 11 kHz or 22 kHz pulse code modulation (PCM).
CF_TIFF	Tagged-image file format.
CF_UNICODETEXT	Windows NT only: Unicode text format. Each line ends with a carriage return/linefeed (CR-LF) combination. A null character signals the end of the data.
The operating system performs implicit data format conversions between certain clipboard formats when an application calls the GetClipboardData function. For example, if the CF_OEMTEXT format is on the clipboard, a window can retrieve data in the CF_TEXT format. The format on the clipboard is converted to the requested format on demand. The following table shows the clipboard data type conversions that are available. Note that some of these automatic type conversions are not available on all platforms.

Clipboard Format	Conversion Format	Platform Support
CF_BITMAP	CF_DIB	Windows 95
CF_DIB	CF_BITMAP	Windows 95
CF_DIB	CF_PALETTE	Windows 95
CF_ENHMETAFILE	CF_METAFILEPICT	Windows 95, Windows NT
CF_METAFILEPICT	CF_ENHMETAFILE	Windows 95, Windows NT
CF_OEMTEXT	CF_TEXT	Windows 95, Windows NT
CF_OEMTEXT	CF_UNICODETEXT	Windows NT
CF_TEXT	CF_OEMTEXT	Windows 95, Windows NT
CF_TEXT	CF_UNICODETEXT	Windows NT
CF_UNICODETEXT	CF_OEMTEXT	Windows NT
CF_UNICODETEXT	CF_TEXT	Windows NT
If the operating system provides an automatic type conversion for a particular clipboard format, there is no advantage to placing the conversion format(s) on the clipboard.

When copying bitmaps, it is best to place only the CF_DIB format on the clipboard. This is because the colors in a device-dependent bitmap (CF_BITMAP) are relative to the system palette, which may change before the bitmap is pasted. If only the CF_DIB format is on the clipboard and a window requests the CF_BITMAP format, the system renders the device-dependent bitmap using the current palette at that time.

If you place the CF_BITMAP format on the clipboard (and not CF_DIB), the system renders the CF_DIB clipboard format as soon as the clipboard is closed. This ensures that the correct palette is used to generate the device-independent bitmap (DIB). Conversions between other clipboard formats occur upon demand.

Windows platforms support two clipboard formats for metafiles: CF_ENHMETAFILE and CF_METAFILEPICT. Specify CF_ENHMETAFILE for enhanced metafiles and CF_METAFILEPICT for Windows metafiles.

See Also

BITMAPINFO, GetClipboardData, GlobalAlloc, METAFILEPICT, OpenClipboard, RealizePalette, RegisterClipboardFormat, SelectPalette, WM_ASKCBFORMATNAME, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, WM_RENDERFORMAT, WM_RENDERALLFORMATS, WM_SIZECLIPBOARD, WM_VSCROLLCLIPBOARD


SetClipboardViewer

The SetClipboardViewer function adds the specified window to the chain of clipboard viewers. Clipboard viewer windows receive a WM_DRAWCLIPBOARD message whenever the content of the clipboard changes.

HWND SetClipboardViewer(

HWND  hwnd	// handle of clipboard viewer window
);
Parameters

hwnd

Identifies the window to be added to the clipboard chain.

Return Value

If the function succeeds, the return value identifies the next window in the clipboard viewer chain. If an error occurs or there are no other windows in the clipboard viewer chain, the return value is NULL. To get extended error information, call GetLastError.

Remarks

The windows that are part of the clipboard viewer chain, called clipboard viewer windows, must process the clipboard messages WM_CHANGECBCHAIN and WM_DRAWCLIPBOARD. Each clipboard viewer window calls the SendMessage function to pass these messages to the next window in the clipboard viewer chain.

A clipboard viewer window must eventually remove itself from the clipboard viewer chain by calling the ChangeClipboardChain function — for example, in response to the WM_DESTROY message.

See Also

ChangeClipboardChain, GetClipboardViewer, SendMessage, WM_CHANGECBCHAIN, WM_DRAWCLIPBOARD


SetColorAdjustment

The SetColorAdjustment function sets the color adjustment values for a device context using the specified values.

BOOL SetColorAdjustment(

HDC  hdc,	// handle of device context
CONST COLORADJUSTMENT *  lpca	// address of coloradjustment structure
);
Parameters

hdc

Identifies the device context.

lpca

Points to a COLORADJUSTMENT structure containing the color adjustment values.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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

COLORADJUSTMENT, SetStretchBltMode, StretchBlt, StretchDIBits


SetColorSpace  (preliminaryWindows 95)
SetColorSpace  (preliminary−Windows 95)

The SetColorSpace function sets the color space for the specified device context, defining the endpoints of the logical RGB space in CIE XYZ space.

BOOL SetColorSpace(

HDC
HCOLORSPACE  hColorSpace
);
Parameters

hdc

Handle to the device context.

hColorSpace

Handle to the logical color space.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

RGB


SetCommBreak

The SetCommBreak function suspends character transmission for a specified communications device and places the transmission line in a break state until the ClearCommBreak function is called.

BOOL SetCommBreak(

HANDLE  hCommDev	// handle of communications device
);
Parameters

hCommDev

Identifies the communications device. The CreateFile function returns this handle.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The SetCommBreak function does not flush data that has not been transmitted.

See Also

ClearCommBreak, CreateFile


SetCommConfig  (preliminaryWindows 95)
SetCommConfig  (preliminary−Windows 95)

The SetCommConfig function sets the current configuration of a communications device.

BOOL SetCommConfig(

HANDLE hCommDev,	// handle of communications device
LPBYTE lpCC,	// address of comm. configuration services
DWORD dwSize	// size of structure
);
Parameters

hCommDev

Identifies the open communications device.

lpCC

Points to a COMMCONFIG structure.

dwSize

Specifies the size, in bytes, of the structure pointed to by lpCC.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

COMMCONFIG


SetCommMask

The SetCommMask function specifies a set of events to be monitored for a communications device.

BOOL SetCommMask(

HANDLE  hCommDev,	// handle of communications device
DWORD  fdwEvtMask	// mask that identifies enabled events
);
Parameters

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	A character was received and placed in the input buffer.
EV_RXFLAG	The event character was received and placed in the input buffer. The event character is specified in the device's DCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY	The last character in the output buffer was sent.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The SetCommMask function specifies the set of events that can be monitored for a particular communications resource. A handle to the communications resource can be specified in a call to the WaitCommEvent function, which waits for one of the events to occur. To get the current event mask of a communications resource, use the GetCommMask function.

If SetCommMask is called for a communications resource while an overlapped wait is pending for that resource, WaitCommEvent returns an error.

See Also

CreateFile, DCB, GetCommMask, SetCommState, WaitCommEvent


SetCommState

The SetCommState function configures a communications device according to the specifications in a device-control block (a DCB structure). The function reinitializes all hardware and control settings, but it does not empty output or input queues.

BOOL SetCommState(

HANDLE  hCommDev,	// handle of communications device
LPDCB  lpdcb	// address of device-control block structure
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The SetCommState function uses a DCB structure to specify the desired configuration. The GetCommState function returns the current configuration.

To set only a few members of the DCB structure, you should modify a DCB structure that has been filled in by a call to GetCommState. This ensures that the other members of the DCB structure have appropriate values.

The SetCommState function fails if the XonChar member of the DCB structure is equal to the XoffChar member.

When SetCommState is used to configure the 8250, the following restrictions apply to the values for the DCB structure's ByteSize and StopBits members:

•	The number of data bits must be 5 to 8 bits.

•	The use of 5 data bits with 2 stop bits is an invalid combination, as are 6, 7, or 8 data bits with 1.5 stop bits.

See Also

BuildCommDCB, CreateFile, DCB, GetCommState


SetCommTimeouts

The SetCommTimeouts function sets the time-out parameters for all read and write operations on a specified communications device.

BOOL SetCommTimeouts(

HANDLE  hCommDev,	// handle of communications device
LPCOMMTIMEOUTS  lpctmo	// address of communications time-out structure
);
Parameters

hCommDev

Identifies the communications device. The CreateFile function returns this handle.

lpctmo

Points to a COMMTIMEOUTS structure that contains the new time-out values.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

COMMTIMEOUTS, GetCommTimeouts, ReadFile, ReadFileEx, WriteFile, WriteFileEx


SetComputerName

The SetComputerName function sets the computer name to be used the next time the system is restarted.

BOOL SetComputerName(

LPCTSTR  lpszName	// address of new computer name
);
Parameters

lpszName

Points to a null-terminated character string that specifies the name that will be the computer name the next time the computer is started. The name must not be longer than MAX_COMPUTERNAME_LENGTH characters.

Windows 95: If this string contains one or more characters that are outside the standard character set, those characters are coerced into standard characters.

Windows NT: If this string contains one or more characters that are outside the standard character set, SetComputerName returns ERROR_INVALID_PARAMETER. It does not coerce the characters outside the standard set.

The standard character set includes letters, numbers, and the following symbols: ! @ # $ % ^ & ' ) ( . - _ { } ~ .

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Applications using this function must have administrator rights.

See Also

GetComputerName


SetConsoleActiveScreenBuffer

The SetConsoleActiveScreenBuffer function sets the specified screen buffer to be the currently displayed console screen buffer.

BOOL SetConsoleActiveScreenBuffer(

HANDLE  hConsoleOutput	// handle of console screen buffer
);
Parameters

hConsoleOutput

Identifies a console screen buffer.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A console can have multiple screen buffers. SetConsoleActiveScreenBuffer determines which one is displayed. You can write to an inactive screen buffer and then use SetConsoleActiveScreenBuffer to display the buffer's contents.

See Also

CreateConsoleScreenBuffer


SetConsoleCP

The SetConsoleCP function sets the input code page used by the console associated with the calling process. A console uses its input code page to translate keyboard input into the corresponding character value.

BOOL SetConsoleCP(

UINT  IDCodePage	// code page to set
);
Parameters

IDCodePage

Specifies the identifier of the code page to set. The identifiers of the code pages available on the local computer are stored in the registry under the following key.

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages.

To determine a console's current input code page, use the GetConsoleCP function. To set and retrieve a console's output code page, use the SetConsoleOutputCP and GetConsoleOutputCP functions.

See Also

GetConsoleCP, GetConsoleOutputCP, SetConsoleOutputCP


SetConsoleCtrlHandler

The SetConsoleCtrlHandler function adds or removes an application-defined HandlerRoutine function from the list of handler functions for the calling process. If no handler function is specified, the function sets an inheritable attribute that determines whether the calling process ignores CTRL+C signals.

BOOL SetConsoleCtrlHandler(

PHANDLER_ROUTINE  pHandlerRoutine,	// address of handler function
BOOL  fAdd	// handler to add or remove
);
Parameters

pHandlerRoutine

Points to the application-defined HandlerRoutine function 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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Each console process has its own list of application-defined HandlerRoutine functions that handle CTRL+C and CTRL+BREAK signals. The handler functions also handle signals generated by the system when the user closes the console, logs off, or shuts down the system. Initially, the handler list for each process contains only a default handler function that calls the ExitProcess function. A console process adds or removes additional handler functions by calling the SetConsoleCtrlHandler function, which does not affect the list of handler functions for other processes. When a console process receives any of the control signals, its handler functions are called on a last-registered, first-called basis until one of the handlers returns TRUE. If none of the handlers returns TRUE, the default handler is called.

For console processes, the CTRL+C and CTRL+BREAK key combinations are typically treated as signals (CTRL_C_EVENT and CTRL_C_BREAK_EVENT). When a console window with the keyboard focus receives CTRL+C or CTRL+BREAK, the signal is typically passed to all processes sharing that console.

CTRL+BREAK is always treated as a signal, but typical CTRL+C behavior can be changed in three ways that prevent the handler functions from being called:

•	The SetConsoleMode function can disable the ENABLE_PROCESSED_INPUT mode for a console's input buffer, so CTRL+C is reported as keyboard input rather than as a signal.

•	Calling SetConsoleCtrlHandler with the NULL and TRUE arguments causes the calling process to ignore CTRL+C signals. This attribute is inherited by child processes, but it can be enabled or disabled by any process without affecting existing processes.

•	If a console process is being debugged and CTRL+C signals have not been disabled, the kernel generates a DBG_CONTROL_C exception. This exception is raised only for the benefit of the debugger, and an application should never use an exception handler to deal with it. If the debugger handles the exception, an application will not notice the CTRL+C, with one exception: alertable waits will terminate. If the debugger passes the exception on unhandled, CTRL+C is passed to the console process and treated as a signal, as previously discussed.

A console process can use the GenerateConsoleCtrlEvent function to send a CTRL+C or CTRL+BREAK signal to a console process group.

The system generates CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUTDOWN_EVENT signals when the user closes the console, logs off, or shuts down the system so that the process has an opportunity to clean up before termination. Console functions, or any C run-time functions that call console functions, may not work reliably during processing of any of the three signals mentioned previously. The reason is that some or all of the internal console cleanup routines may have been called before executing the process signal handler.

See Also

ExitProcess, GenerateConsoleCtrlEvent, GetConsoleMode, HandlerRoutine, SetConsoleMode


SetConsoleCursorInfo

The SetConsoleCursorInfo function sets the size and visibility of the cursor for the specified console screen buffer.

BOOL SetConsoleCursorInfo(

HANDLE  hConsoleOutput,	// handle of console screen buffer
PCONSOLE_CURSOR_INFO  pcci	// address of cursor information
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

When a screen buffer's cursor is visible, its appearance can vary, ranging from completely filling a character cell to showing up as a horizontal line at the bottom of the cell. The dwSize member of the CONSOLE_CURSOR_INFO structure specifies the percentage of a character cell that is filled by the cursor. If this member is less than 1 or greater than 100, SetConsoleCursorInfo fails.

See Also

CONSOLE_CURSOR_INFO, GetConsoleCursorInfo, SetConsoleCursorPosition


SetConsoleCursorPosition

The SetConsoleCursorPosition function sets the cursor position in the specified console screen buffer.

BOOL SetConsoleCursorPosition(

HANDLE  hConsoleOutput,	// handle of console screen buffer
COORD  coordCursor	// new cursor position coordinates
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The cursor position determines where characters written by the WriteFile or WriteConsole function, or echoed by the ReadFile or ReadConsole function, are displayed. To determine the current position of the cursor, use the GetConsoleScreenBufferInfo function.

If the new cursor position is not within the boundaries of the screen buffer's window, the window origin changes to make the cursor visible.

See Also

GetConsoleCursorInfo, GetConsoleScreenBufferInfo, ReadConsole, ReadFile, SetConsoleCursorInfo, WriteConsole, WriteFile


SetConsoleMode

The SetConsoleMode function sets the input mode of a console's input buffer or the output mode of a console screen buffer.

BOOL SetConsoleMode(

HANDLE  hConsole,	// handle of console input or screen buffer
DWORD  fdwMode	// input or output mode to set
);
Parameters

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 this 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 examined for ASCII control sequences and the correct action is performed. Backspace, tab, bell, carriage return, and linefeed characters are processed.
ENABLE_WRAP_AT_EOL_OUTPUT	When writing with WriteFile or WriteConsole or echoing with ReadFile or ReadConsole, the cursor moves to the beginning of the next row when it reaches the end of the current row. This causes the rows displayed in the console window to scroll up automatically when the cursor advances beyond the last row in the window. It also causes the contents of the screen buffer to scroll up (discarding the top row of the screen buffer) when the cursor advances beyond the last row in the screen buffer. If this mode is disabled, the last character in the row is overwritten with any subsequent characters.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A console consists of an input buffer and one or more screen buffers. The mode of a console buffer determines how the console behaves during input and output (I/O) operations. One set of flag constants is used with input handles, and another set is used with screen buffer (output) handles. Setting the output modes of one screen buffer does not affect the output modes of other screen buffers.

The ENABLE_LINE_INPUT and ENABLE_ECHO_INPUT modes only affect processes that use ReadFile or ReadConsole to read from the console's input buffer. Similarly, the ENABLE_PROCESSED_INPUT mode primarily affects ReadFile and ReadConsole users, except that it also determines whether Ctrl+C input is reported in the input buffer (to be read by the ReadConsoleInput function) or is passed to a HandlerRoutine function defined by the application.

The ENABLE_WINDOW_INPUT and ENABLE_MOUSE_INPUT modes determine whether user interactions involving window resizing and mouse actions are reported in the input buffer or discarded. These events can be read by ReadConsoleInput, but they are always filtered by ReadFile and ReadConsole.

The ENABLE_PROCESSED_OUTPUT and ENABLE_WRAP_AT_EOL_OUTPUT modes only affect processes using ReadFile or ReadConsole and WriteFile or WriteConsole.

To determine the current mode of a console input buffer or a screen buffer, use the GetConsoleMode function.

See Also

GetConsoleMode, HandlerRoutine, ReadConsole, ReadConsoleInput, ReadFile, WriteConsole, WriteFile


SetConsoleOutputCP

The SetConsoleOutputCP function sets the output code page used by the console associated with the calling process. A console uses its output code page to translate the character values written by the various output functions into the images displayed in the console window.

BOOL SetConsoleOutputCP(

UINT  IDCodePage	// code page to set
);
Parameters

IDCodePage

Specifies the identifier of the code page to set. The identifiers of the code pages available on the local computer are stored in the registry under the following key.

   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Nls\CodePage

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

A code page maps 256 character codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages.

To determine a console's current output code page, use the GetConsoleOutputCP function. To set and retrieve a console's input code page, use the SetConsoleCP and GetConsoleCP functions.

See Also

GetConsoleCP, GetConsoleOutputCP, SetConsoleCP


SetConsoleScreenBufferSize

The SetConsoleScreenBufferSize function changes the size of the specified console screen buffer.

BOOL SetConsoleScreenBufferSize(

HANDLE  hConsoleOutput,	// handle of console screen buffer
COORD  coordSize	// new size in character rows and cols.
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

COORD, GetConsoleScreenBufferInfo, SetConsoleWindowInfo


SetConsoleTextAttribute

The SetConsoleTextAttribute function sets the foreground (text) and background color attributes of characters written to the screen buffer by the WriteFile or WriteConsole function, or echoed by the ReadFile or ReadConsole function. This function affects only text written after the function call.

BOOL SetConsoleTextAttribute(

HANDLE  hConsoleOutput,	// handle of console screen buffer
WORD  wAttr	// text and background colors
);
Parameters

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

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

To determine the current color attributes of a screen buffer, call the GetConsoleScreenBufferInfo function.

See Also

GetConsoleScreenBufferInfo, ReadConsole, ReadFile, WriteConsole, WriteFile


SetConsoleTitle

The SetConsoleTitle function sets the title bar string for the current console window.

BOOL SetConsoleTitle(

LPTSTR  lpszTitle	// address of new title
);
Parameters

lpszTitle

Points to a null-terminated string that contains the string to appear in the title bar of the console window.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetConsoleTitle


SetConsoleWindowInfo

The SetConsoleWindowInfo function sets the current size and position of a console screen buffer's window.

BOOL SetConsoleWindowInfo(

HANDLE  hConsoleOutput,	// handle of console screen buffer
BOOL  fAbsolute,	// coordinate type flag
PSMALL_RECT  psrctWindowRect	// address of new window rectangle
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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 sizes, but it does not consider the size of the screen buffer.

SetConsoleWindowInfo can be used to scroll the contents of the screen buffer by shifting the position of the window rectangle without changing its size.

See Also

GetConsoleScreenBufferInfo, GetLargestConsoleWindowSize, SMALL_RECT, ScrollConsoleScreenBuffer


SetCurrentDirectory

The SetCurrentDirectory function changes the current directory for the current process.

BOOL SetCurrentDirectory(

LPCTSTR  lpszCurDir	// address of name of new current directory
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Each process has a single current directory made up of two parts:

•	A disk designator that is either a drive letter followed by a colon, or a server name and share name (\\servername\sharename)

•	A directory on the disk designator

See Also

GetCurrentDirectory


SetCursor

The SetCursor function establishes the cursor shape.

HCURSOR SetCursor(

HCURSOR  hcur	// handle of cursor
);
Parameters

hcur

Identifies the cursor. The cursor must have been created by the  CreateCursor or loaded by one of the following functions:

Windows 95: LoadCursor function or LoadImage

Windows NT: LoadCursor

If this parameter is NULL, the cursor is removed from the screen.

Return Value

The return value is the handle of the previous cursor, if there was one. If there was no previous cursor, the return value is NULL.

Remarks

The cursor is set only if the new cursor is different from the previous cursor; otherwise, the function returns immediately.

The cursor is a shared resource. A window should set the cursor shape only when the cursor is in its client area or when the window is capturing mouse input. In systems without a mouse, the window should restore the previous cursor before the cursor leaves the client area or before it relinquishes control to another window.

If your application must set the cursor while it is in a window, make sure the class cursor for the specified window's class is set to NULL. If the class cursor is not NULL, the system restores the class cursor each time the mouse is moved.

The cursor is not shown on the screen if the internal cursor display count is less than zero. This occurs if the application uses the ShowCursor function to hide the cursor more times than to show the cursor.

See Also

CreateCursor, LoadCursor, SetCursorPos, ShowCursor


SetCursorPos

The SetCursorPos function moves the cursor to the specified screen coordinates. If the new coordinates are not within the screen rectangle set by the most recent ClipCursor function, Windows automatically adjusts the coordinates so that the cursor stays within the rectangle.

BOOL SetCursorPos(

int  X,	// horizontal position
int  Y	// vertical position
);
Parameters

X

Specifies the new x-coordinate, in screen coordinates, of the cursor.

Y

Specifies the new y-coordinate, in screen coordinates, of the cursor.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The cursor is a shared resource. A window should move the cursor only when the cursor is in its client area.

The calling process must have WINSTA_WRITEATTRIBUTES access to the window station.

See Also

ClipCursor, GetCursorPos, SetCaretPos, SetCursor, ShowCursor


SetDebugErrorLevel

The SetDebugErrorLevel function sets the minimum error level at which Windows will generate debugging events and pass them to a debugger.

VOID SetDebugErrorLevel(

DWORD  dwLevel	// debugging error level
);
Parameters

dwLevel

Specifies the minimum error level for debugging events. If an error is equal to or above this level, Windows generates a debugging event. This parameter must be one of the following values:

Value	Meaning
0	Does not report any errors. This value is the default error level.
SLE_ERROR	Reports only ERROR level debugging events.
SLE_MINORERROR	Reports only MINORERROR level and ERROR level debugging events.
SLE_WARNING	Reports WARNING level, MINORERROR level, and ERROR level debugging events.
Return Value

This function does not return a value.

Remarks

The debugger calls SetDebugErrorLevel to specify the types of errors that it should be notified about.

If the debugging error level is greater than the error that occurred, the value for the GetLastError function is set, but the kernel does not generate a debugging event.


SetDefaultCommConfig  (preliminaryWindows 95)
SetDefaultCommConfig  (preliminary−Windows 95)

The SetDefaultCommConfig function sets the default configuration for a communications device.

BOOL SetDefaultCommConfig(

LPCSTR lpszName,	//
LPCOMMCONFIG lpCC,	//
DWORD dwSize	//
);
Parameters

lpszName

Points to a null-terminated string specifying the name of the device.

lpCC

Points to a COMMCONFIG structure. If this parameter is NULL, the default configuration is set to the device driver's defaults.

dwSize

Specifies the size, in bytes, of the structure pointed to by lpCC.

Return value

If the function succeeds, the return value is TRUE.

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

See Also

COMMCONFIG


SetDeviceGammaRamp  (preliminaryWindows 95)
SetDeviceGammaRamp  (preliminary−Windows 95)

The SetDeviceGammaRamp function sets the gamma ramp on direct color display boards.

BOOL SetDeviceGammaRamp(

HDC  hdc,
LPVOID  lpRamp
);
Parameters

hdc

Handle to the device context.

lpRamp

Pointer to a set of three arrays of 256-byte elements. These arrays are the mapping between color values in the frame buffer and DAC values. The first array is red, the next is green, and the final one is blue.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Direct color display modes do not use color look-up tables. The direct color modes are usually 16-, 24-, or 32-bit. Not all direct color video boards support loadable gamma ramps. This function succeeds only for those drivers that support loadable gamma ramps in hardware.


SetDIBColorTable

The SetDIBColorTable function sets RGB (red, green, blue) color values in a range of entries in the color table of the device-independent bitmap (DIB) that is currently selected into a specified device context.

UINT SetDIBColorTable(

HDC hdc,	// handle of device context whose DIB is of interest
UINT uStartIndex,	// color table index of first entry to set
UINT cEntries,	// number of color table entries to set
RGBQUAD *pColors	// pointer to array of color table entries
);
Parameters

hdc

Specifies a device context. A device-independent bitmap must be selected into this device context.

uStartIndex

A zero-based color table index that specifies the first color table entry to set.

cEntries

Specifies the number of color table entries to set.

pColors

Points to an array of RGBQUAD structures containing new color information for the DIB's color table.

Return Value

If the function succeeds, the return value is the number of color table entries that the function sets.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

This function should be called to set the color table for device-independent bitmaps that use 1, 4, or 8 bits per pixel. The biBitCount member of a bitmap's associated BITMAPINFOHEADER structure specifies the number of bits per pixel. Device-independent bitmaps with a biBitCount value greater than 8 do not have a color table.

See Also

BITMAPINFOHEADER, CreateDIBSection, GetDIBColorTable, GetObject, DIBSECTION, RGBQUAD


SetDIBits

The SetDIBits function sets the pixels in a bitmap using the color data found in the specified device-independent bitmap (DIB).

int SetDIBits(

HDC  hdc,	// handle of device context
HBITMAP  hbmp,	// handle of bitmap
UINT  uStartScan,	// starting scan line
UINT  cScanLines,	// number of scan lines
CONST VOID *  lpvBits,	// array of bitmap bits
CONST BITMAPINFO *  lpbmi,	// address of structure with bitmap data
UINT  fuColorUse	// type of color indices to use
);
Parameters

hdc

Identifies a device context.

hbmp

Identifies the bitmap that is to be altered using the color data from the specified DIB.

uStartScan

Specifies the starting scan line for the device-independent color data in the array pointed to by the lpvBits parameter.

cScanLines

Specifies the number of scan lines found in the array containing device-independent color data.

lpvBits

Points to the DIB color data, stored as an array of bytes. The format of the bitmap values depends on the biBitCount member of the BITMAPINFO structure pointed to by the lpbmi parameter.

lpbmi

Points to a BITMAPINFO data structure that contains information about the DIB.

fuColorUse

Specifies whether the bmiColors member of the BITMAPINFO structure was provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or palette indices. The fuColorUse parameter must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	The color table consists of an array of 16-bit indices into the logical palette of the device context identified by the hdc parameter.
DIB_RGB_COLORS	The color table is provided and contains literal RGB values.
Return Value

If the function succeeds, the return value is the number of scan lines copied.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Optimal bitmap drawing speed is obtained when the bitmap bits are indices into the system palette.

Applications can retrieve the system palette colors and indices by calling the GetSystemPaletteEntries function. After the colors and indices are retrieved, the application can create the DIB.

The device context identified by the hdc parameter is used only if the DIB_PAL_COLORS constant is set for the fuColorUse parameter; otherwise it is ignored.

The bitmap identified by the hbmp parameter must not be selected into a device context when the application calls this function.

The origin for bottom-up DIBs is the lower-left corner of the bitmap; the origin for top-down DIBs is the upper-left corner of the bitmap.

See Also

BITMAPINFO, GetSystemPaletteEntries


SetDIBitsToDevice

The SetDIBitsToDevice function sets the pixels in the specified rectangle on the device that is associated with the destination device context using color data from a device-independent bitmap (DIB).

int SetDIBitsToDevice(

HDC  hdc,	// handle of device context
int  XDest,	// x-coordinate of upper-left corner of dest. rect.
int  YDest,	// y-coordinate of upper-left corner of dest. rect.
DWORD  dwWidth,	// source rectangle width
DWORD  dwHeight,	// source rectangle height
int  XSrc,	// x-coordinate of lower-left corner of source rect.
int  YSrc,	// y-coordinate of lower-left corner of source rect.
UINT  uStartScan,	// first scan line in array
UINT  cScanLines,	// number of scan lines
CONST VOID *  lpvBits,	// address of array with DIB bits
CONST BITMAPINFO *  lpbmi,	// address of structure with bitmap info.
UINT  fuColorUse	// RGB or palette indices
);
Parameters

hdc

Identifies the device context.

XDest

Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.

YDest

Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.

dwWidth

Specifies the width, in logical units, of the DIB.

dwHeight

Specifies the height, in logical units, of the DIB.

XSrc

Specifies the x-coordinate, in logical units, of the lower-left corner of the DIB.

YSrc

Specifies the y-coordinate, in logical units, of the lower-left corner of the DIB.

uStartScan

Specifies the starting scan line in the DIB.

cScanLines

Specifies the number of DIB scan lines contained in the array pointed to by the lpvBits parameter.

lpvBits

Points to DIB color data stored as an array of bytes.

lpbmi

Points to a BITMAPINFO structure that contains information about the DIB.

fuColorUse

Specifies whether the bmiColors member of the BITMAPINFO structure contains explicit red, green, blue (RGB) values or indices into a palette. The fuColorUse parameter must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	The color table consists of an array of 16-bit indices into the currently selected logical palette.
DIB_RGB_COLORS	The color table contains literal RGB values.
Return Value

If the function succeeds, the return value is the number of scan lines set.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Optimal bitmap drawing speed is obtained when the bitmap bits are indices into the system palette.

Applications can retrieve the system palette colors and indices by calling the GetSystemPaletteEntries function. After the colors and indices are retrieved, the application can create the DIB.

The origin of a bottom-up DIB is the lower-left corner of the bitmap; the origin of a top-down DIB is the upper-left corner.

To reduce the amount of memory required to set bits from a large device-independent bitmap on a device surface, an application can band the output by repeatedly calling SetDIBitsToDevice, placing a different portion of the bitmap into the lpvBits array each time. The values of the uStartScan and cScanLines parameters identify the portion of the bitmap contained in the lpvBits array.

Windows 95: The SetDIBitsToDevice function returns an error if it is called by a process that is running in the background while a full-screen MS-DOS runs in the foreground.

See Also

BITMAPINFO, GetSystemPaletteEntries, SetDIBits, StretchDIBits


SetDlgItemInt

The SetDlgItemInt function sets the text of a control in a dialog box to the string representation of a specified integer value.

BOOL SetDlgItemInt(

HWND  hwndDlg,	// handle of dialog box
int  idControl,	// identifier of control
UINT  uValue,	// value to set
BOOL  fSigned	// signed or unsigned indicator
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

To set the new text, this function sends a WM_SETTEXT message to the specified control.

See Also

GetDlgItemInt, SetDlgItemText, WM_SETTEXT


SetDlgItemText

The SetDlgItemText function sets the title or text of a control in a dialog box.

BOOL SetDlgItemText(

HWND  hwndDlg,	// handle of dialog box
int  idControl,	// identifier of control
LPCTSTR  lpsz	// text to set
);
Parameters

hwndDlg

Identifies the dialog box that contains the control.

idControl

Identifies the control with a title or text that is to be set.

lpsz

Points to the null-terminated string that contains the text to be copied to the control.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The SetDlgItemText function sends a WM_SETTEXT message to the specified control.

See Also

GetDlgItemInt, GetDlgItemText, SetDlgItemInt, WM_SETTEXT


SetDoubleClickTime

The SetDoubleClickTime function sets the double-click time for the mouse. A double-click is a series of two clicks of a mouse button, the second occurring within a specified time after the first. The double-click time is the maximum number of milliseconds that may occur between the first and second clicks of a double-click.

BOOL SetDoubleClickTime(

UINT  uInterval	// double-click interval
);
Parameters

uInterval

Specifies the number of milliseconds that may occur between the first and second clicks of a double-click. If this parameter is set to zero, Windows uses the default double-click time of 500 milliseconds.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The SetDoubleClickTime function alters the double-click time for all windows in the system.

See Also

GetDoubleClickTime


SetEndOfFile

The SetEndOfFile function moves the end-of-file (EOF) position for the specified file to the current position of the file pointer.

BOOL SetEndOfFile(

HANDLE  hFile	// handle of file whose EOF is to be set
);
Parameters

hFile

Identifies the file to have its EOF position moved. The file handle must have been created with GENERIC_WRITE access to the file.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

This function can be used to truncate or extend a file. If the file is extended, the contents of the file between the old EOF position and the new position are not defined.

If you called CreateFileMapping to create a file-mapping object for hFile, you must first call UnmapViewOfFile to unmap all views and call CloseHandle to close the file-mapping object before you can call SetEndOfFile.

See Also

CloseHandle, CreateFile, CreateFileMapping, UnmapViewOfFile


SetEnhMetaFileBits

The SetEnhMetaFileBits function creates a memory-based enhanced-format metafile from the supplied data.

HENHMETAFILE SetEnhMetaFileBits(

UINT  cbBuffer,	// buffer size
CONST BYTE *  lpData	// buffer that contains enhanced metafile data
);
Parameters

cbBuffer

Specifies the size, in bytes, of the data provided.

lpData

Points to a buffer that contains enhanced-metafile data. (It is assumed that the data in the buffer was obtained by calling the GetEnhMetaFileBits function.)

Return Value

If the function succeeds, the return value is a handle of a memory-based enhanced metafile.

If the function fails, the return value is NULL.

Remarks

When the application no longer needs the enhanced-metafile handle, it should delete the handle by calling the DeleteEnhMetaFile function.

The SetEnhMetaFileBits function does not accept metafile data in the Windows format. To import Windows-format metafiles, use the SetWinMetaFileBits function.

See Also

DeleteEnhMetaFile, GetEnhMetaFileBits, SetWinMetaFileBits


SetEnvironmentVariable

The SetEnvironmentVariable function sets the value of an environment variable for the current process.

BOOL SetEnvironmentVariable(

LPCTSTR  lpszName,	// address of environment variable name
LPCTSTR  lpszValue	// address of new value for variable
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetEnvironmentVariable


SetErrorMode

The SetErrorMode function controls how the operating system handles several types of serious errors. You can specify that the operating system will handle these errors or that the application will receive and handle them.

UINT SetErrorMode(

UINT  fuErrorMode	// set of bit flags that specify error-handling properties
);
Parameters

fuErrorMode

A set of bit flags that specify system error-handling properties. The following error mode bit flag constants are defined; you can set any combination of them:

Value	Action
SEM_FAILCRITICALERRORS	If this flag is set, the operating system does not display the critical-error-handler message box when such an error occurs. Instead, the operating system sends the error to the calling process.
SEM_NOALIGNMENTFAULTEXCEPT	If this flag is set, the operating system automatically fixes memory alignment faults and makes them invisible to the application. It does this for the calling process and any descendant processes.  This flag always affects MIPS processors. It has no effect on x86 processors. If the registry value \CurrentControlSet\Control\Session Manager:EnableAlignmentFaultExceptions is set to REG_DWORD 0x0, this key has no effect on ALPHA processors. That is the system default. If the registry key is set to REG_DWORD 0x1, the SEM_NOALIGNMENTFAULTEXCEPT flag does affect ALPHA processors.
SEM_NOGPFAULTERRORBOX	If this flag is set, the operating system does not display the general-protection-fault message box when such an error occurs. This flag should only be set by debugging applications that handle general protection (GP) faults themselves via an appropriate exception handler.
SEM_NOOPENFILEERRORBOX	If this flag is set, the operating system does not display a message box when it fails to find a a file. Instead, the error is returned to the calling process.
Return Value

The return value is the previous state of the error-mode bit flags.

Remarks

A child process inherits the error mode of its parent process.

The default state for the error mode properties set by this function is OFF.

On some non-x86 processors misaligned memory references cause an alignment fault exception. The SEM_NOALIGNMENTFAULTEXCEPT flag lets you control whether the operating system automatically fixes such alignment faults, or makes them visible to an application.

The SEM_NOALIGNMENTFAULTEXCEPT flag always affects MIPS processors. It never affects x86 processors. It affects ALPHA processors only if the registry key \CurrentControlSet\Control\Session Manager:EnableAlignmentFaultExceptions is set to REG_DWORD 0x1. The default setting for that registry key is REG_DWORD 0x0.

On an x86 platform, an application doesn't need to do anything to have the operating system automatically fix misaligned memory references. The operating system does not make alignment faults visible to an application.

On a MIPS platform, an application must explicitly call SetErrorMode, setting the SEM_NOALIGNMENTFAULTEXCEPT flag, to have the operating system automatically fix alignment faults. The default setting is for the operating system to make alignment faults visible to an application.

On an ALPHA platform, the operating system automatically fixes alignment faults, unless the aforementioned registry key is set to REG_DWORD 0x1. When that registry key is set to REG_DWORD 0x1, the operating system makes alignment faults visible to an application, and an application must then call SetErrorMode to have the operating system automatically fix alignment faults.

Specifying the SEM_NOALIGNMENTFAULTEXCEPT flag on x86 systems is not an error, but implementations of Windows NT are free to silently ignore and not properly preserve the flag. This means that code sequences such as the following are not always valid on x86 systems:

SetErrorMode(SEM_NOALIGNMENTFAULTEXCEPT);

fuOldErrorMode = SetErrorMode(0);

ASSERT(fuOldErrorMode == SEM_NOALIGNMENTFAULTEXCEPT);


SetEvent

The SetEvent function sets the state of the specified event object to signaled.

BOOL SetEvent(

HANDLE  hEvent	// handle of event object
);
Parameters

hEvent

Identifies the event object. The CreateEvent or OpenEvent function returns this handle, which must have EVENT_MODIFY_STATE access.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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


SetFileApisToANSI

The SetFileApisToANSI function causes a set of Win32 file functions to use the ANSI character set code page. This function is useful for 8-bit console input and output operations.

VOID SetFileApisToANSI (VOID)

Parameters

This function has no parameters.

Return Value

This function has no return value.

Remarks

The SetFileApisToANSI function complements the SetFileApisToOEM function, which causes the same set of Win32 file functions to use the OEM character set code page.

The 8-bit console functions use the OEM code page by default. All other functions use the ANSI code page by default. This means that strings returned by the console functions may not be processed correctly by other functions, and vice versa. For example, if the FindFirstFileA function returns a string that contains certain extended ANSI characters, and the 8-bit console functions are set to use the OEM code page, then the WriteConsoleA function will not display the string properly.

Use the AreFileApisANSI function to determine which code page the set of file functions is currently using. Use the SetConsoleCP and SetConsoleOutputCP functions to set the code page for the 8-bit console functions.

To solve the problem of code page incompatibility, it is best to use Unicode for console applications. Console applications that use Unicode are much more versatile than those that use 8-bit console functions. Barring that solution, a console application can call the SetFileApisToOEM function to cause the set of Win32 file functions to use OEM character set strings rather than ANSI character set strings. Use the SetFileApisToANSI function to set those functions back to the ANSI code page.

SetFileApisToANSI and SetFileApisToOEM affect these Win32 functions:

_lopen	GetDriveType	LoadLibrary
CopyFile	GetFileAttributes	LoadLibraryEx
CreateDirectory	GetFullPathName	MoveFile
CreateFile	GetModuleFileName	MoveFileEx
CreateProcess	GetModuleHandle	OpenFile
DeleteFile	GetSystemDirectory	RemoveDirectory
FindFirstFile	GetTempFileName	SearchPath
FindNextFile	GetTempPath	SetCurrentDirectory
GetCurrentDirectory	GetVolumeInformation	SetFileAttributes
GetDiskFreeSpace	GetWindowsDirectory
When dealing with command lines, a console application should obtain the command line in Unicode form, and then convert it to OEM form using the relevant character-to-OEM functions. Note also that the argv function uses the ANSI character set.

See Also

AreFileApisANSI, FindFirstFileA, SetFileApisToOEM, SetConsoleCP, SetConsoleOutputCP, WriteConsoleA,


SetFileApisToOEM

The SetFileApisToOEM function causes a set of Win32 file functions to use the OEM character set code page. This function is useful for 8-bit console input and output operations.

VOID SetFileApisToOEM(VOID)

Parameters

This function has no parameters.

Return Value

This function has no return value.

Remarks

The SetFileApisToOEM function is complemented by the SetFileApisToANSI function, which causes the same set of Win32 file functions to use the ANSI character set code page.

The 8-bit console functions use the OEM code page by default. All other functions use the ANSI code page by default. This means that strings returned by the console functions may not be processed correctly by other functions, and vice versa. For example, if the FindFirstFileA function returns a string that contains certain extended ANSI characters, and the 8-bit console functions are set to use the OEM code page, then the WriteConsoleA function will not display the string properly.

Use the AreFileApisANSI function to determine which code page the set of file functions is currently using. Use the SetConsoleCP and SetConsoleOutputCP functions to set the code page for the 8-bit console functions.

To solve the problem of code page incompatibility, it is best to use Unicode for console applications. Console applications that use Unicode are much more versatile than those that use 8-bit console functions. Barring that solution, a console application can call the SetFileApisToOEM function to cause the set of Win32 file functions to use OEM character set strings rather than ANSI character set strings. Use the SetFileApisToANSI function to set those functions back to the ANSI code page.

SetFileApisToANSI and SetFileApisToOEM affect these Win32 functions:

_lopen	GetDriveType	LoadLibrary
CopyFile	GetFileAttributes	LoadLibraryEx
CreateDirectory	GetFullPathName	MoveFile
CreateFile	GetModuleFileName	MoveFileEx
CreateProcess	GetModuleHandle	OpenFile
DeleteFile	GetSystemDirectory	RemoveDirectory
FindFirstFile	GetTempFileName	SearchPath
FindNextFile	GetTempPath	SetCurrentDirectory
GetCurrentDirectory	GetVolumeInformation	SetFileAttributes
GetDiskFreeSpace	GetWindowsDirectory
When dealing with command lines, a console application should obtain the command line in Unicode form, and then convert it to OEM form using the relevant character-to-OEM functions. Note also that the argv function uses the ANSI character set.

See Also

AreFileApisANSI, FindFirstFileA, SetConsoleCP, SetConsoleCP, SetConsoleOutputCP, SetFileApisToANSI, WriteConsoleA,


SetFileAttributes

The SetFileAttributes function sets a file's attributes.

BOOL SetFileAttributes(

LPCTSTR  lpFileName,	// address of filename
DWORD  dwFileAttributes	// address of attributes to set
);
Parameters

lpFileName

Points to a string that specifies the name of the file whose attributes are to be set.

Windows 95: This string must not exceed MAX_PATH characters.

Windows NT: There is a default string size limit for paths of MAX_PATH characters. This limit is related to how the SetFileAttributes function parses paths. An application can transcend this limit and send in paths longer than MAX_PATH characters by calling the wide (W) version of SetFileAttributes and prepending "\\?\" to the path. The "\\?\" tells the function to turn off path parsing; it lets paths longer than MAX_PATH be used with SetFileAttributesW. This also works with UNC names. The "\\?\" is ignored as part of the path. For example, "\\?\C:\myworld\private" is seen as "C:\myworld\private", and "\\?\UNC\bill_g_1\hotstuff\coolapps" is seen as "\\bill_g_1\hotstuff\coolapps".

dwFileAttributes

Specifies the file attributes to set for the file. This parameter can be a combination of the following values. However, all other values override FILE_ATTRIBUTE_NORMAL.

Value	Meaning
FILE_ATTRIBUTE_ARCHIVE	The file is an archive file. Applications use this value to mark files for backup or removal.
FILE_ATTRIBUTE_NORMAL	The file has no other attributes set. This value is valid only if used alone.
FILE_ATTRIBUTE_HIDDEN	The file is hidden. It is not 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 the operating system or is used exclusively by it.
FILE_ATTRIBUTE_TEMPORARY	The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.
Windows 95 only: FILE_ATTRIBUTE_ATOMIC_WRITE	Reserved for future use; do not specify.
Windows 95 only: FILE_ATTRIBUTE_XACTION_WRITE	Reserved for future use; do not specify.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

You cannot use the SetFileAttribute function to set a file's compression state. Setting FILE_ATTRIBUTE_COMPRESSED in the dwFileAttributes parameter does nothing. Use the DeviceIoControl function and the FSCTL_SET_COMPRESSION operation to set a file's compression state.

See Also

DeviceIoControl, FSCTL_SET_COMPRESSION, GetFileAttributes


SetFilePointer

The SetFilePointer function moves the file pointer of an open file.

DWORD SetFilePointer(

HANDLE  hFile,	// handle of file
LONG  lDistanceToMove,	// number of bytes to move file pointer
PLONG  lpDistanceToMoveHigh,	// address of high-order word of distance to move
DWORD  dwMoveMethod	// how to move
);
Parameters

hFile

Identifies the file whose file pointer is to be moved. The file handle must have been created with GENERIC_READ or GENERIC_WRITE access to the file.

lDistanceToMove

Specifies the number of bytes to move the file pointer. A positive value moves the pointer forward in the file and a negative value moves it backward.

lpDistanceToMoveHigh

Points to the high-order word of the 64-bit distance to move. If the value of this parameter is NULL, SetFilePointer can operate only on files whose maximum size is 2^32 − 2. If this parameter is specified, the maximum file size is 2^64 − 2. This parameter also receives the high-order word of the new value of the file pointer.

dwMoveMethod

Specifies the starting point for the file pointer move. This parameter can be one of the following values:

Value	Meaning
FILE_BEGIN	The starting point is zero or the beginning of the file. If FILE_BEGIN is specified, DistanceToMove is interpreted as an unsigned location for the new file pointer.
FILE_CURRENT	The current value of the file pointer is the starting point.
FILE_END	The current end-of-file position is the starting point.
Return Value

If the SetFilePointer function succeeds, the return value is the low-order doubleword of the new file pointer, and if lpDistanceToMoveHigh is not NULL, the function puts the high-order doubleword of the new file pointer into the LONG pointed to by that parameter.

If the function fails and lpDistanceToMoveHigh is NULL, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

If the function fails, and lpDistanceToMoveHigh is non-NULL, the return value is 0xFFFFFFFF and GetLastError will return a value other than NO_ERROR.

Remarks

You cannot use the SetFilePointer function with a handle to a nonseeking device, such as a pipe or a communications device. To determine the file type for hFile, use the GetFileType function.

You should be careful when setting the file pointer in a multithreaded application. For example, an application whose threads share a file handle, update the file pointer, and read from the file must protect this sequence by using a critical section object or mutex object.

If the hFile file handle was opened with the FILE_FLAG_NO_BUFFERING flag set, an application can move the file pointer only to sector-aligned positions. A sector-aligned position is a position that is a whole number multiple of the volume's sector size. An application can obtain a volume's sector size by calling the GetDiskFreeSpace function. If an application calls SetFilePointer with distance-to-move values that result in a position that is not sector-aligned and a handle that was opened with FILE_FLAG_NO_BUFFERING, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

Note that if the return value is 0xFFFFFFFF and if lpDistanceToMoveHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed. The following sample code illustrates this point:

//

// Case One: calling the function with

//           lpDistanceToMoveHigh == NULL

// try to move hFile's file pointer some distance

dwPointer = SetFilePointer (hFile, lDistance,

                            NULL, FILE_BEGIN) ;

// if we failed ...

if (dwPointer == 0xFFFFFFFF) {

    // obtain the error code

    dwError = GetLastError() ;

    // deal with that failure

    .

    .

    .

    } // end of error handler

//

// Case Two: calling the function with

//           lpDistanceToMoveHigh != NULL

// try to move hFile's file pointer some huge distance

dwPointerLow = SetFilePointer (hFile, lDistanceLow,

                               & lDistanceHigh, FILE_BEGIN) ;

// if we failed ...

if (dwPointerLow == 0xFFFFFFFF

    &&

    (dwError = GetLastError()) != NO_ERROR ){

    // deal with that failure

    .

    .

    .

    } // end of error handler

See Also

GetDiskFreeSpace, GetFileType, ReadFile, ReadFileEx, WriteFile, WriteFileEx


SetFileSecurity

The SetFileSecurity function sets the security of a file or directory object.

BOOL SetFileSecurity(

LPCTSTR  lpszFile,	// address of string for filename
SECURITY_INFORMATION  si,	// type of information to set
PSECURITY_DESCRIPTOR  psd	// address of security descriptor
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The SetFileSecurity function is successful only if the following conditions are met:

•	If the object's owner is being set, the calling process must have either WRITE_OWNER permission or be the object's owner.

•	If the object's discretionary access-control list (ACL) is being set, the calling process must have either WRITE_DAC permission or be the object's owner.

•	If the object's system ACL is being set, the SE_SECURITY_NAME privilege must be enabled for the calling process.

See Also

GetFileSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetKernelObjectSecurity, SetPrivateObjectSecurity, SetUserObjectSecurity


SetFileTime

The SetFileTime function sets the date and time that a file was created, last accessed, or last modified.

BOOL SetFileTime(

HANDLE  hFile,	// identifies the file
CONST FILETIME *  lpftCreation,	// time the file was created
CONST FILETIME *  lpftLastAccess,	// time the file was last accessed
CONST FILETIME *  lpftLastWrite	// time the file was last written
);
Parameters

hFile

Identifies the file for which to set the dates and times. The file handle must have been created with GENERIC_WRITE access to the file.

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.

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.

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The FAT, NTFS, and HPFS file systems all support the file creation, last access, and last write time values.

See Also

FILETIME, GetFileSize, GetFileTime, GetFileType


SetFocus

The SetFocus function sets the keyboard focus to the specified window. All subsequent keyboard input is directed to this window. The window, if any, that previously had the keyboard focus loses it.

HWND SetFocus(

HWND  hwnd	// handle of window to receive focus
);
Parameters

hwnd

Identifies the window that will receive the keyboard input. If this parameter is NULL, keystrokes are ignored.

Return Value

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.

Remarks

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 the SetForegroundWindow function.

See Also

GetActiveWindow, GetFocus, SetActiveWindow, SetCapture, SetForegroundWindow, WM_KILLFOCUS, WM_SETFOCUS, WM_SYSCHAR, WM_SYSKEYDOWN, WM_SYSKEYUP


SetForegroundWindow

The SetForegroundWindow function puts the thread that created the specified window into the foreground and activates the window. Keyboard input is directed to the window, and various visual cues are changed for the user.

BOOL SetForegroundWindow(

HWND  hwnd	// handle of window to bring to foreground
);
Parameters

hwnd

Identifies the window that should be activated and brought to the foreground.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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


SetForm

The SetForm function sets the form information for the specified printer.

BOOL SetForm(

HANDLE  hPrinter,	// handle of printer object
LPTSTR  lpszForm,	// address of form name
DWORD  dwLevel,	// structure level
LPBYTE  lpbForm	// address of structure array
);
Parameters

hPrinter

Identifies the printer for which the form information is set.

lpszForm

Points to a null-terminated string that specifies 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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The printer handle hPrinter is obtained by calling the OpenPrinter function.

See Also

FORM_INFO_1, OpenPrinter


SetGraphicsMode

The SetGraphicsMode function sets the graphics mode for the specified device context.

int SetGraphicsMode(

HDC  hdc,	// handle of the device context
int  iMode	// graphics mode
);
Parameters

hdc

Identifies the device context.

iMode

Specifies the graphics mode. This parameter can be one of the following values:

Value	Meaning
GM_COMPATIBLE	Sets the graphics mode that is compatible with Windows version 3.1. This is the default mode. If this value is specified, the application can only modify the world-to-device transform by calling functions that set window and viewport extents and origins, but not by using SetWorldTransform or ModifyWorldTransform; calls to those functions will fail. Examples of functions that set window and viewport extents and origins are SetViewportExtEx and SetWindowExtEx.
GM_ADVANCED	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.
Return Value

If the function succeeds, the return value is the old graphics mode.

If the function fails, the return value is zero.

Remarks

There are three areas in which graphics output differs according to the graphics mode:

1.	Text Output: In the GM_COMPATIBLE mode, TrueType (or vector font) text output behaves much the same way as raster font text output with respect to the world-to-device transform in the DC. The TrueType text is always written from left to right and right side up, even if the rest of the graphics will be flipped in the x or y axis. Only the height of the TrueType (or vector font) text is scaled appropriately. The only way to write nonhorizontal text in the GM_COMPATIBLE mode is to specify nonzero escapement and orientation for the logical font selected in this device context.

In the GM_ADVANCED mode, TrueType (or vector font) text output fully conforms to the world-to-device transform in the device context. The raster fonts only have very limited transformation capabilities (stretching by some integer factors). Graphics device interface (GDI) tries to produce the best output it can with raster fonts for non-trivial transforms.

2.	Rectangle Exclusion: If the default GM_COMPATIBLE graphics mode is set, the system excludes bottom and rightmost edges when it draws rectangles.

The GM_ADVANCED graphics mode is required if applications want to draw rectangles that are bottom-right inclusive.

3.	Arc Drawing: If the default GM_COMPATIBLE graphics mode is set, GDI draws arcs using the current arc direction in the device space. With this convention, arcs do not respect page-to-device transforms that require a flip along the x or y axis.

If the GM_ADVANCED graphics mode is set, GDI always draws arcs in the counterclockwise direction in logical space. This is equivalent to the statement that, in the GM_ADVANCED graphics mode, both arc control points and arcs themselves fully respect the device context's world-to-device transform.

See Also

CreateDC, GetArcDirection, GetDC, GetGraphicsMode, ModifyWorldTransform; SetArcDirection, SetViewportExtent, SetViewportExtEx, SetWindowExtent, SetWindowExtEx, SetWorldTransform


SetHandleCount

The SetHandleCount function changes the number of file handles available to a process.

The SetHandleCount function is not necessary under the Windows NT implementation of Win32; in fact, it 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.

UINT SetHandleCount(

UINT  cHandles	// number of file handles needed
);
Parameters

cHandles

Specifies the number of file handles needed by the application. The maximum value is implementation-dependent. Under Win32s, the maximum value is 255.

Return Value

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.

Remarks

Under Windows NT, the maximum number of files that an application can open is determined by the amount of available non-paged memory pool, because each open file handle consumes part of that resource.


SetHandleInformation  (preliminaryWindows NT)
SetHandleInformation  (preliminary−Windows NT)

The SetHandleInformation function sets certain properties of an object handle. The information is specified as a set of bit flags.

BOOL GetHandleInformation (

HANDLE  hObject,	// handle to an object
DWORD  dwMask,	// specifies flags to change
DWORD  dwFlags	// specifies new values for flags
);
Parameters

hObject

Specifies a handle to an object. The SetHandleInformation function sets information associated with this object handle.

dwMask

A mask that specifies the bit flags to be changed. Use the same flag constants shown in the description of dwFlags.

dwFlags

A set of bit flags that specify properties of the object handle. The following flags are defined:

Value	Meaning
HANDLE_FLAG_INHERIT	If this flag is set, a child process created with the bInheritHandles parameter of CreateProcess set to TRUE will inherit the object handle.
HANDLE_FLAG_PROTECT_FROM_CLOSE	If this flag is set, calling the CloseHandle function will not close the object handle.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Note that you must set a change mask bit flag in dwMask in order to set or clear the associated bit flag in dwFlags.

See Also

CreateProcess, CloseHandle, GetHandleInformation


SetICMMode  (preliminaryWindows 95)
SetICMMode  (preliminary−Windows 95)

The SetICMMode function enables or disables image color matching for the specified device context.

BOOL SetICMMode(

HDC  hdc,
int  fICM
);
Parameters

hdc

Handle to the device context.

fICM

Set to ICM_ON to turn on image color matching; ICM_OFF to turn it off; and ICM_QUERY to return the current mode.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

If ICM_QUERY is specified, the function returns ICM_ON or ICM_OFF to indicate the current mode.


SetICMProfile  (preliminaryWindows 95)
SetICMProfile  (preliminary−Windows 95)

The SetICMProfile function sets the color profile for the specified device context.

BOOL SetICMProfile(

HDC  hdc,
LPTSTR  lpFileName
);
Parameters

hdc

Handle to the device context.

lpFileName

Pointer to a null-terminated string that names the color profile file.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


SetJob

The SetJob function pauses, resumes, cancels, or restarts a print job on the specified printer. The function can also be used to set print job parameters such as the job priority, the document name, and so forth.

BOOL SetJob(

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
);
Parameters

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. This parameter 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.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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 members of a JOB_INFO_1 or JOB_INFO_2 structure are ignored on a call to SetJob:

JobId, pPrinterName, pMachineName, pDrivername, Size, Submitted, and Time.

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 specify the JOB_POSITION_UNSPECIFIED (0) value for the Position member.

See Also

JOB_INFO_1, JOB_INFO_2, OpenPrinter, SetPrinter


SetKernelObjectSecurity

The SetKernelObjectSecurity function sets the security of a kernel object. For example, this can be a process, thread, or event.

BOOL SetKernelObjectSecurity(

HANDLE  hObject,	// handle of object
SECURITY_INFORMATION  si,	// type of information to set
PSECURITY_DESCRIPTOR  psd	// address of security descriptor
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The SetKernelObjectSecurity function is successful only if the following conditions are met:

•	If the object's owner is being set, the calling process must have either WRITE_OWNER permission or be the object's owner.

•	If the object's discretionary access-control list (ACL) is being set, the calling process must have either WRITE_DAC permission or be the object's owner.

•	If the object's system ACL is being set, the SE_SECURITY_NAME privilege must be enabled for the calling process.

See Also

GetKernelObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetFileSecurity, SetPrivateObjectSecurity, SetUserObjectSecurity


SetKeyboardState

The SetKeyboardState function copies a 256-byte array of keyboard key states into the calling thread's keyboard-input state table. This is the same table accessed by the GetKeyboardState and GetKeyState functions. Changes made to this table do not affect keyboard input to any other thread.

BOOL SetKeyboardState(

LPBYTE  lpbKeyState	// address of array with virtual-key codes
);
Parameters

lpbKeyState

Points to a 256-byte array that contains keyboard key states.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Because the SetKeyboardState function alters the input state of the calling thread and not the global input state of the system, an application cannot use SetKeyboardState to set the NUM LOCK, CAPS LOCK, or SCROLL LOCK indicator lights on the keyboard.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyState, MapVirtualKey


SetLastError

The SetLastError function sets the last-error code for the calling thread.

VOID SetLastError(

DWORD  fdwError	// per-thread error code
);
Parameters

fdwError

Specifies the last-error code for the thread.

Remarks

Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no Win32 API error code has this bit set. If you are defining an error code for your application, set this bit to indicate that the error code has been defined by your application and to ensure that your error code does not conflict with any system-defined error codes.

This function is intended primarily for dynamic-link libraries (DLLs). Calling this function after an error occurs lets the DLL emulate the behavior of a Win32 function.

Most Win32 functions call SetLastError when they fail. Function failure is typically indicated by a return value error code such as FALSE, NULL, 0xFFFFFFFF, or −1. Some functions call SetLastError under conditions of success; those cases are noted in each function's reference page.

Applications can retrieve the value saved by this function by using the GetLastError function. The use of GetLastError is optional; an application can call it to find out the specific reason for a function failure.

The last-error code is kept in thread local storage so that multiple threads do not overwrite each other's values.

See Also

GetLastError, SetLastErrorEx, TlsGetValue


SetLastErrorEx

The SetLastErrorEx function sets the last-error code. In Windows 95 and in Windows NT, this function is identical to the SetLastError function. The second parameter is not implemented.

VOID SetLastErrorEx(

DWORD  fdwError,	// per-thread error code
DWORD  fdwType	// error type
);
Parameters

fdwError

Specifies the last-error code for the 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 code is set without reporting anything to the debugger. Specifying this value is equivalent to using the SetLastError function.
Remarks

Error codes are 32-bit values (bit 31 is the most significant bit). Bit 29 is reserved for application-defined error codes; no Win32 API error code has this bit set. If you are defining an error code for your application, set this bit to indicate that the error code has been defined by the application and to ensure that your error code does not conflict with any system-defined error codes.

This function is intended primarily for dynamic-link libraries (DLLs). Calling this function after an error occurs allows the DLL to emulate the behavior of the Win32 API.

Most Win32 functions call SetLastError when they fail. Function failure is typically indicated by a return value error code such as FALSE, NULL, 0xFFFFFFFF, or −1. Some functions call SetLastError under conditions of success; those cases are noted in each function's reference page.

Applications can retrieve the value saved by this function by using the GetLastError function.

The last-error code is kept in thread local storage so that multiple threads do not overwrite each other's values.

See Also

GetLastError, SetLastError


SetLocaleInfo

The SetLocaleInfo function sets an item of locale information. It does so by making an entry in the process portion of the locale table. This setting only affects the user override portion of the locale settings; it does not set the system defaults.

Only certain types of locale information, or LCTYPE values, can be set by this function. See the following Remarks section for a list of valid LCTYPE values.

The locale information is always passed in as a null-terminated Unicode string in the Unicode (W) version of the function, and as a null-terminated ANSI string in the ANSI (A) version. No integers are allowed by this function; any numeric values must be specified as Unicode or ANSI text. Each LCTYPE has a particular format.

BOOL SetLocaleInfo(

LCID  Locale,	// locale identifier
LCTYPE  LCType,	// type of information to set
LPCTSTR  lpLCData	// pointer to information to set
);
Parameters

Locale

Specifies the locale whose information the function will set.

LCType

Specifies the type of locale information to be set by the function. Note that only one LCTYPE may be specified per call. Not all LCTYPE values are valid; see the list of valid LCTYPE values in the following Remarks section.

lpLCData

Points to a null-terminated string containing the locale information the function will set. This should be an LPWSTR for the Unicode (W) version of the function, and an LPSTR for the ANSI (A) version. The information must be in the specified LCTYPE's particular format.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INVALID_ACCESS

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

The following LCTYPE values are valid for this function:

LOCALE_ICALENDARTYPE	LOCALE_SDATE
LOCALE_ICURRDIGITS	LOCALE_SDECIMAL
LOCALE_ICURRENCY	LOCALE_SGROUPING
LOCALE_IDIGITS	LOCALE_SLIST
LOCALE_IFIRSTDAYOFWEEK	LOCALE_SLONGDATE
LOCALE_IFIRSTWEEKOFYEAR	LOCALE_SMONDECIMALSEP
LOCALE_ILZERO	LOCALE_SMONGROUPING
LOCALE_IMEASURE	LOCALE_SMONTHOUSANDSEP
LOCALE_INEGCURR	LOCALE_SNEGATIVESIGN
LOCALE_INEGNUMBER	LOCALE_SPOSITIVESIGN
LOCALE_ITIME	LOCALE_SSHORTDATE
LOCALE_S1159	LOCALE_STHOUSAND
LOCALE_S2359	LOCALE_STIME
LOCALE_SCURRENCY	LOCALE_STIMEFORMAT
See Also

GetLocaleInfo


SetLocalTime

The SetLocalTime function sets the current local time and date.

BOOL SetLocalTime(

CONST SYSTEMTIME *  lpst	// address of local time to set
);
Parameters

lpst

Points to a SYSTEMTIME structure that contains the current local date and time.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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

See Also

AdjustTokenPrivileges, GetLocalTime, GetSystemTime, SetSystemTimeAdjustment, SYSTEMTIME


SetMailslotInfo

The SetMailslotInfo function sets the time-out value used by the specified mailslot for a read operation.

BOOL SetMailslotInfo(

HANDLE  hMailslot,	// mailslot handle
DWORD  dwReadTimeout	// read time-out
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The initial time-out value used by a mailslot for a read operation is typically set by CreateMailslot when the mailslot is created.

See Also

CreateMailslot, GetMailslotInfo


SetMapMode

The SetMapMode function sets the mapping mode of the specified device context. The mapping mode defines the unit of measure used to transform page-space units into device-space units, and also defines the orientation of the device's x and y axes.

int SetMapMode(

HDC  hdc,	// handle of device context
int  fnMapMode	// new mapping mode
);
Parameters

hdc

Identifies the device context.

fnMapMode

Specifies the new mapping mode. It can be any one of the following values:

Value	Description
MM_ANISOTROPIC	Logical units are mapped to arbitrary units with arbitrarily scaled axes. Use the SetWindowExtEx and SetViewportExtEx functions to specify the units, orientation, and scaling that you want.
MM_HIENGLISH	Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is up.
MM_HIMETRIC	Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is up.
MM_ISOTROPIC	Logical units are mapped to arbitrary units with equally scaled axes; that is, one unit along the x-axis is equal to one unit along the y-axis. Use the SetWindowExtEx and SetViewportExtEx functions to specify the units and the orientation of the axes that you want. Graphics device interface (GDI) makes adjustments as necessary to ensure the x and y units remain the same size (for example, if you set the window extent, the viewport will be adjusted to keep the units isotropic).
MM_LOENGLISH	Each logical unit is mapped to 0.01 inch. Positive x is to the right; positive y is up.
MM_LOMETRIC	Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is up.
MM_TEXT	Each logical unit is mapped to one device pixel. Positive x is to the right; positive y is down.
MM_TWIPS	Each logical unit is mapped to one twentieth of a printer's point (1/1440 inch, also called a "twip"). Positive x is to the right; positive y is up.
Return Value

If the function succeeds, the return value identifies the previous mapping mode.

If the function fails, the return value is zero.

Remarks

The MM_TEXT mode allows applications to work in device pixels, whose size varies from device to device.

The MM_HIENGLISH, MM_HIMETRIC, MM_LOENGLISH, MM_LOMETRIC, and MM_TWIPS modes are useful for applications drawing in physically meaningful units (such as inches or millimeters).

The MM_ISOTROPIC mode ensures a 1:1 aspect ratio.

The MM_ANISOTROPIC mode allows the x-coordinates and y-coordinates to be adjusted independently.

See Also

GetMapMode, SetViewportExtEx, SetViewportOrgEx, SetWindowExtEx, SetWindowOrgEx


SetMapperFlags

The SetMapperFlags function alters the algorithm the font mapper uses when it maps logical fonts to physical fonts.

DWORD SetMapperFlags(

HDC  hdc,	// handle of device context
DWORD  dwFlag	// font-mapper flag
);
Parameters

hdc

Identifies the device context that contains the font-mapper flag.

dwFlag

Specifies whether the font mapper should attempt to match a font's aspect ratio to the current device's aspect ratio. If bit zero is set, the mapper selects only matching fonts.

Return Value

If the function succeeds, the return value is the previous value of the font-mapper flag.

If the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

Remarks

If the dwFlag parameter is set and no matching fonts exist, Windows chooses a new aspect ratio and retrieves a font that matches this ratio.

The remaining bits of the dwFlag parameter must be zero.

See Also

GetAspectRatioFilterEx


SetMenu

The SetMenu function assigns a new menu to the specified window.

BOOL SetMenu(

HWND  hwnd,	// handle of window
HMENU  hmenu	// handle of menu
);
Parameters

hwnd

Identifies the window to which the menu is to be assigned.

hmenu

Identifies the new menu. If this parameter is NULL, the window's current menu is removed.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The window is redrawn to reflect the menu change.

The SetMenu function replaces the previous menu, if any, but it does not destroy it. An application should call the DestroyMenu function to accomplish this task.

See Also

DestroyMenu, GetMenu


SetMenuContextHelpId  (preliminaryWindows NT)
SetMenuContextHelpId  (preliminary−Windows NT)

The SetMenuContextHelpId function associates a help context identifier with a menu. All items in the menu share this identifier. It is not possible to attach a help context identifier to the individual menu items.

BOOL SetMenuContextHelpId(

HMENU  hmenu,
DWORD  dwContextHelpId
);
Parameters

hmenu

Handle to the menu with which to associate the help context identifier.

dwContextHelpId

Help context identifier.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


SetMenuDefaultItem  (preliminaryWindows 95)
SetMenuDefaultItem  (preliminary−Windows 95)

The SetMenuDefaultItem function sets the default menu item for the specified menu.

BOOL SetMenuDefaultItem(

HMENU  hMenu,
UINT  uItem,
UINT  fByPos
);
Parameters

hMenu

Handle to the menu to set the default item for.

uItem

Identifier or position of the new default menu item or − 1 for no default item. The meaning of this parameter depends on the value of fByPos.

fByPos

Value specifying the meaning of uItem. If this parameter is FALSE, uItem is a menu item identifier. Otherwise, it is a menu item position.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.


SetMenuItemBitmaps

The SetMenuItemBitmaps function associates the specified bitmap with a menu item. Whether the menu item is checked or unchecked, Windows displays the appropriate bitmap next to the menu item.

BOOL SetMenuItemBitmaps(

HMENU  hmenu,	// handle of menu
UINT  uItem,	// menu item to receive new bitmaps
UINT  fuFlags,	// menu item flags
HBITMAP  hbmUnchecked,	// handle of unchecked bitmap
HBITMAP  hbmChecked	// handle of checked bitmap
);
Parameters

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 uItem gives the identifier of the menu item. If neither MF_BYCOMMAND nor MF_BYPOSITION is specified, MF_BYCOMMAND is the default flag.
MF_BYPOSITION	Indicates that uItem 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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If 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

GetMenu, GetMenuCheckMarkDimensions


SetMenuItemInfo  (preliminaryWindows 95)
SetMenuItemInfo  (preliminary−Windows 95)

The SetMenuItemInfo function changes information about a menu item.

BOOL WINAPI SetMenuItemInfo(

HMENU  hMenu,
UINT  uItem,
BOOL  fByPosition,
LPMENUITEMINFO  lpmii
);
Parameters

hMenu

Handle to the menu that contains the menu item.

uItem

Identifier or position of the menu item to change. The meaning of this parameter depends on the value of fByPosition.

fByPosition

Value specifying the meaning of uItem. If this parameter is FALSE, uItem is a menu item identifier. Otherwise, it is a menu item position.

lpmii

Pointer to a MENUITEMINFO structure that contains information about the menu item and specifies which menu item attributes to change.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

See Also

MENUITEMINFO


SetMessageExtraInfo  (preliminaryWindows 95)
SetMessageExtraInfo  (preliminary−Windows 95)

The SetMessageExtraInfo function sets the extra message information for the current thread. Extra message information is an application- or driver-defined 32-bit value associated with the current thread's message queue. An application can use the GetMessageExtraInfo function to retrieve a thread's extra message information.

LPARAM SetMessageExtraInfo(

LPARAM  lParam	// application-defined 32-bit value
);
Parameters

lParam

Specifies the 32-bit value to associate with the current thread.

Return Value

The return value is the previous 32-bit value.

See Also

GetMessageExtraInfo


SetMessageQueue

The SetMessageQueue function creates a new message queue. It is useful in Windows version 3.x applications that require a queue that contains more than eight messages (the maximum size of the default queue). It does nothing running with Win32, because queues are expanded dynamically as necessary.

BOOL SetMessageQueue(

int  cMessagesMax	// size of message queue
);


SetMetaFileBits

The SetMetaFileBits function is not implemented in the Win32 API. Win32-based applications should use the SetMetaFileBitsEx function.


SetMetaFileBitsEx

The SetMetaFileBitsEx function creates a memory-based Windows-format metafile from the supplied data.

This function is provided for compatibility with earlier versions of Microsoft Windows. Win32-based applications should use the SetEnhMetaFileBits function.

HMETAFILE SetMetaFileBitsEx(

UINT  nSize,	// size of Windows-format metafile
CONST BYTE *  lpData	// address of buffer containing metafile data
);
Parameters

nSize

Specifies the size, in bytes, of the Windows-format metafile.

lpData

Points to a buffer that contains the Windows-format metafile. (It is assumed that the data was obtained by using the GetMetaFileBitsEx function.)

Return Value

If the function succeeds, the return value is a handle of a memory-based Windows-format metafile.

If the function fails, the return value is NULL.

Remarks

A Windows-format metafile does not support the new curve, path, and transformation functions such as PolyBezier, BeginPath, and SetWorldTransform. Applications that use these new functions and use metafiles to store pictures created by these functions should use the enhanced-format metafile functions.

To convert a Windows-format metafile into an enhanced-format metafile, use the SetWinMetaFileBits function.

When the application no longer needs the metafile handle returned by SetMetaFileBitsEx, it should delete it by calling the DeleteMetaFile function.

See Also

BeginPath, DeleteMetaFile, GetMetaFileBitsEx, PolyBezier, SetEnhMetaFileBits, SetWinMetaFileBits, SetWorldTransform


SetMetaRgn

The SetMetaRgn function intersects the current clipping region for the specified device context with the current metaregion and saves the combined region as the new metaregion for the specified device context. The clipping region is reset to a null region.

int SetMetaRgn(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value specifies the new clipping region's complexity and can be any one of the following values:

Value	Meaning
NULLREGION	Region is empty.
SIMPLEREGION	Region is a single rectangle.
COMPLEXREGION	Region is more than one rectangle.
ERROR	An error occurred. (The previous clipping region is unaffected.)
Remarks

The current clipping region of a device context is defined by the intersection of its clipping region and its metaregion.

The SetMetaRgn function should only be called after an application's original device context was saved by calling the SaveDC function.

See Also

GetMetaRgn, SaveDC


SetMiterLimit

The SetMiterLimit function sets the limit for the length of miter joins for the specified device context.

BOOL SetMiterLimit(

HDC  hdc,	// handle of device context
FLOAT  eNewLimit,	// new miter limit
PFLOAT  peOldLimit	// previous miter limit
);
Parameters

hdc

Identifies the device context.

eNewLimit

Specifies the new miter limit for the device context.

peOldLimit

Points to a floating-point value that receives the previous miter limit. If this parameter is NULL, the previous miter limit is not returned.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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


SetNamedPipeHandleState

The SetNamedPipeHandleState function sets the read mode and the blocking mode of the specified named pipe. If the specified handle is to the client end of a named pipe and if the named pipe server process is on a remote computer, the function can also be used to control local buffering.

BOOL SetNamedPipeHandleState(

HANDLE  hNamedPipe,	// handle of named pipe
LPDWORD  lpdwMode,	// address of new pipe mode
LPDWORD  lpcbMaxCollect,	// address of max. bytes before remote transmission
LPDWORD  lpdwCollectDataTimeout	// address of max. time before remote transmission
);
Parameters

hNamedPipe

Identifies the named pipe instance. This parameter can be a handle to the server end of the pipe, as returned by the CreateNamedPipe function, or to the client end of the pipe, as returned by the CreateFile function. The handle must have GENERIC_WRITE access to the named pipe.

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. This parameter can be NULL if the mode is not being set. One of the following read modes can be specified:

Mode	Description
PIPE_READMODE_BYTE	Data is read from the pipe as a stream of bytes. This mode is the default if no read-mode flag is specified.
PIPE_READMODE_MESSAGE	Data is read from the pipe as a stream of messages. The function fails if this flag is specified for a byte-type pipe.
One of the following wait modes can be specified:

Mode	Description
PIPE_WAIT	Blocking mode is enabled. This mode is the default if no wait-mode flag is specified. When a blocking mode pipe handle is specified in the ReadFile, WriteFile, or ConnectNamedPipe function, operations are not finished until there is data to read, all data is written, or a client is connected. Use of this mode can mean waiting indefinitely in some situations for a client process to perform an action.
PIPE_NOWAIT	Nonblocking mode is enabled. In this mode, ReadFile, WriteFile, and ConnectNamedPipe always return immediately. Note that nonblocking mode is supported for compatibility with Microsoft® LAN Manager version 2.0 and should not be used to achieve asynchronous input and output (I/O) with named pipes.
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 specified pipe handle is to the server end of a named pipe or if client and server processes are on the same machine. This parameter is ignored if the client process specifies the FILE_FLAG_WRITE_THROUGH flag in the CreateFile function when the handle was created. This parameter can be NULL if the collection count is not being set.

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. This parameter can be NULL if the collection count is not being set.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

ConnectNamedPipe, CreateFile, CreateNamedPipe, GetNamedPipeHandleState, ReadFile, WriteFile


SetPaletteEntries

The SetPaletteEntries function sets RGB (red, green, blue) color values and flags in a range of entries in a logical palette.

UINT SetPaletteEntries(

HPALETTE  hpal,	// handle of logical palette
UINT  iStart,	// index of first entry to set
UINT  cEntries,	// number of entries to set
CONST PALETTEENTRY  *lppe	// address of array of structures
);
Parameters

hpal

Identifies the logical palette.

iStart

Specifies the first logical-palette entry to be set.

cEntries

Specifies the number of logical-palette entries to be set.

lppe

Points to the first member of an array of PALETTEENTRY structures containing the RGB values and flags.

Return Value

If the function succeeds, the return value is the number of entries that were set in the logical palette.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application can determine whether or not a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

Even if a logical palette has been selected and realized, changes to the palette do not affect the physical palette in the surface. RealizePalette must be called again to set the new logical palette into the surface.

See Also

GetDeviceCaps, RealizePalette, PALETTEENTRY


SetParent

The SetParent function changes the parent window of the specified child window.

HWND SetParent(

HWND  hwndChild,	// handle of window whose parent is changing
HWND  hwndNewParent	// handle of new parent window
);
Parameters

hwndChild

Identifies the child window.

hwndNewParent

Identifies the new parent window. If this parameter is NULL, the desktop window becomes the new parent window.

Return Value

If the function succeeds, the return value is the handle of the previous parent window.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

An application can use the SetParent function to set the parent window of a pop-up, overlapped, or child window. The new parent window and the child window must belong to the same application.

If the window identified by the hwndChild parameter is visible, Windows performs the appropriate redrawing and repainting.

See Also

GetParent


SetPixel

The SetPixel function sets the pixel at the specified coordinates to the specified color.

COLORREF SetPixel(

HDC  hdc,	// handle of device context
int  X,	// x-coordinate of pixel
int  Y,	// y-coordinate of pixel
COLORREF  crColor	// pixel color
);
Parameters

hdc

Identifies the device context.

X

Specifies the x-coordinate, in logical units, of the point to be set.

Y

Specifies the y-coordinate, in logical units, of the point to be set.

crColor

Specifies the color to be used to paint the point.

Return Value

If the function succeeds, the return value is the RGB value that the function sets the pixel to. This value may differ from the color specified by crColor; that happens when an exact match for the specified color cannot be found.

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

Remarks

The function fails if the pixel coordinates lie outside of the current clipping region.

Not all devices support the SetPixel function. For more information, see GetDeviceCaps.

See Also

GetDeviceCaps, SetPixelV


SetPixelV

The SetPixelV function sets the pixel at the specified coordinates to the closest approximation of the specified color. The point must be in the clipping region and the visible part of the device surface.

BOOL SetPixelV(

HDC  hdc,	// handle of device context
int  X,	// x-coordinate of pixel
int  Y,	// y-coordinate of pixel
COLORREF  crColor	// new pixel color
);
Parameters

hdc

Identifies the device context.

X

Specifies the x-coordinate, in logical units, of the point to be set.

Y

Specifies the y-coordinate, in logical units, of the point to be set.

crColor

Specifies the color to be used to paint the point.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Not all devices support the SetPixelV function. For more information, see the description of the RC_BITBLT capability in the GetDeviceCaps function.

SetPixelV is faster than SetPixel because it does not need to return the color value of the point actually painted.

See Also

GetDeviceCaps, SetPixel


SetPolyFillMode

The SetPolyFillMode function sets the polygon fill mode for functions that fill polygons.

int SetPolyFillMode(

HDC  hdc,	// handle of device context
int  iPolyFillMode	// polygon fill mode
);
Parameters

hdc

Identifies the device context.

iPolyFillMode

Specifies the new fill mode. This parameter can be either of the following values:

Value	Meaning
ALTERNATE	Selects alternate mode (fills the area between odd-numbered and even-numbered polygon sides on each scan line).
WINDING	Selects winding mode (fills any region with a nonzero winding value).
Return Value

The return value specifies the previous filling mode. If an error occurs, the return value is zero.

Remarks

In general, the modes differ only in cases where a complex, overlapping polygon must be filled (for example, a five-sided polygon that forms a five-pointed star with a pentagon in the center). In such cases, ALTERNATE mode fills every other enclosed region within the polygon (that is, the points of the star), but WINDING mode fills all regions (that is, the points and the pentagon).

When the fill mode is ALTERNATE, GDI fills the area between odd-numbered and even-numbered polygon sides on each scan line. That is, GDI fills the area between the first and second side, between the third and fourth side, and so on.

When the fill mode is WINDING, GDI fills any region that has a nonzero winding value. This value is defined as the number of times a pen used to draw the polygon would go around the region. The direction of each edge of the polygon is important.

See Also

GetPolyFillMode


SetPrinter

The SetPrinter function sets the specified printer by pausing printing, resuming printing, or clearing all print jobs. The function can also be used to set printer data.

BOOL SetPrinter(

HANDLE  hPrinter,	// handle of printer object
DWORD  dwLevel,	// structure level
LPBYTE  lpbPrinter,	// address of array containing printer data
DWORD  dwCommand	// printer-state command
);
Parameters

hPrinter

Identifies the printer.

dwLevel

Windows 95: Specifies the type of data contained in lpbPrinter. This parameter must be 0, 2, 3, 4, or 5. This parameter must be zero if dwCommand is not equal to zero.

Windows NT: Specifies the type of data contained in lpbPrinter. This parameter must be 0, 2, or 3. This parameter must be zero if dwCommand is not equal to zero.

lpbPrinter

Windows 95: Contains either a DWORD value indicating the printer status or points to an array of bytes that may contain printer data. If dwLevel is 0, and the dwCommand parameter is PRINTER_CONTROL_STATUS, lpbPrinter must contain a DWORD value that specifies the new printer status to set. For a list of the possible status values, see the Status member of the PRINTER_INFO_2 structure. Note that PRINTER_STATUS_PAUSED and PRINTER_STATUS_PENDING_DELETION are not valid status values to set. Otherwise, when dwLevel is 0, this parameter must be NULL. If dwLevel is 2, 3, 4, or 5, lpbPrinter points to an array that contains PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4, or PRINTER_INFO_5 structures, respectively.

Windows NT: Contains either a DWORD value indicating the printer status or points to an array of bytes that may contain printer data. For a list of the possible status values, see the Status member of the PRINTER_INFO_2 structure. Note that PRINTER_STATUS_PAUSED and PRINTER_STATUS_PENDING_DELETION are not valid status values to set. Otherwise, when dwLevel is 0, this parameter must be NULL. If dwLevel is 2 or 3, lpbPrinter points to an array that contains PRINTER_INFO_2 or PRINTER_INFO_3 structures, respectively.

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.
PRINTER_CONTROL_SET_STATUS	Windows 95: Sets the printer status.
If dwCommand is any of the above values, dwLevel must be zero.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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 SetPrinter function ignores the following members of a PRINTER_INFO_2 structure:

pServerName, AveragePPM, Status, and cJobs

Pausing a printer suspends scheduling of all print jobs for that printer, except for the one print job that may be currently printing. Print jobs can be submitted to a paused printer, but no jobs will be scheduled to print on that printer until printing is resumed. If a printer is cleared, all print jobs for that printer are deleted, except for the current print job.

If the printer data structure contains a pointer to a security descriptor, only those components of the security descriptor that the caller has permission to write should be present. An application that wants to write particular security descriptor components must open the printer with sufficient access permission to modify those components. The following table shows the security descriptor components that can be modified for particular access permission values:

Access Permission	Modifiable Security Descriptor Components
WRITE_OWNER	Owner, primary proup
WRITE_DAC	Discretionary access-control list (ACL)
ACCESS_SYSTEM_SECURITY	System ACL
If the calling application lacks a required permission, SetPrinter fails. Those components of a security descriptor that an application does not wish to modify should be NULL or not be present, as appropriate. If you do not want to modify the security descriptor, and are calling SetPrinter with a PRINTER_INFO_2 structure, set the pSecurityDescriptor member of that structure to NULL.

See Also

AddPrinter, GetPrinter, OpenPrinter, PRINTER_INFO_2, PRINTER_INFO_3


SetPrinterData

The SetPrinterData function sets the configuration data for a printer.

DWORD SetPrinterData(

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
);
Parameters

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 and Windows 95.
REG_DWORD_BIG_ENDIAN	A 32-bit number in big-endian format. In big-endian format, the most significant byte of a word is the low-order 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.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is an error value.

Remarks

The handle hPrinter is obtained by calling the OpenPrinter function.

Existing configuration data for a printer can be retrieved by calling the GetPrinter function.

See Also

GetPrinter, OpenPrinter


SetPriorityClass

The SetPriorityClass function sets the priority class for the specified process. This value together with the priority value of each thread of the process determines each thread's base priority level.

BOOL SetPriorityClass(

HANDLE  hProcess,	// handle to the process
DWORD  fdwPriority	// priority class value
);
Parameters

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
HIGH_PRIORITY_CLASS	Indicates a process that performs time-critical tasks that must be executed immediately for it to run correctly. The threads of a high-priority class process preempt the threads of normal or idle priority class processes. An example is Windows Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all available cycles.
IDLE_PRIORITY_CLASS	Indicates a process whose threads run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle-priority class is inherited by child processes.
NORMAL_PRIORITY_CLASS	Indicates a normal process with no special scheduling needs.
REALTIME_PRIORITY_CLASS	Indicates a process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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
HIGH_PRIORITY_CLASS	13
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
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
1	Idle, normal, or high class, THREAD_PRIORITY_IDLE
2	Idle class, THREAD_PRIORITY_LOWEST
3	Idle class, THREAD_PRIORITY_BELOW_NORMAL
4	Idle class, THREAD_PRIORITY_NORMAL
5	Background normal class, THREAD_PRIORITY_LOWEST Idle class, THREAD_PRIORITY_ABOVE_NORMAL
6	Background normal class, THREAD_PRIORITY_BELOW_NORMAL Idle class, THREAD_PRIORITY_HIGHEST
7	Foreground normal class, THREAD_PRIORITY_LOWEST Background normal class, THREAD_PRIORITY_NORMAL
8	Foreground normal class, THREAD_PRIORITY_BELOW_NORMAL Background normal class, THREAD_PRIORITY_ABOVE_NORMAL
9	Foreground normal class, THREAD_PRIORITY_NORMAL Background normal class, THREAD_PRIORITY_HIGHEST
10	Foreground normal class, THREAD_PRIORITY_ABOVE_NORMAL
11	High class, THREAD_PRIORITY_LOWEST Foreground normal class, THREAD_PRIORITY_HIGHEST
12	High class, THREAD_PRIORITY_BELOW_NORMAL
13	High class, THREAD_PRIORITY_NORMAL
14	High class, THREAD_PRIORITY_ABOVE_NORMAL
15	Idle, normal, or high class, THREAD_PRIORITY_TIME_CRITICAL High class, THREAD_PRIORITY_HIGHEST
16	Real-time class, THREAD_PRIORITY_IDLE
22	Real-time class, THREAD_PRIORITY_LOWEST
23	Real-time class, THREAD_PRIORITY_BELOW_NORMAL
24	Real-time class, THREAD_PRIORITY_NORMAL
25	Real-time class, THREAD_PRIORITY_ABOVE_NORMAL
26	Real-time class, THREAD_PRIORITY_HIGHEST
31	Real-time class, THREAD_PRIORITY_TIME_CRITICAL
See Also

CreateProcess, CreateThread, GetPriorityClass, GetThreadPriority, SetThreadPriority


SetPrivateObjectSecurity

The SetPrivateObjectSecurity function modifies a private object's security descriptor.

BOOL SetPrivateObjectSecurity(

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 structure
HANDLE  hClientToken	// handle of client access token
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The object's security descriptor must be in self-relative form.

If necessary, the SetPrivateObjectSecurity function allocates additional memory to produce a larger security descriptor.

The SetPrivateObjectSecurity function is successful only if the following conditions are met:

•	If the object's owner is being set, the calling process must have either WRITE_OWNER permission or be the object's owner.

•	If the object's discretionary access-control list (ACL) is being set, the calling process must have either WRITE_DAC permission or be the object's owner.

•	If the object's system ACL is being set, the SE_SECURITY_NAME privilege must be enabled for the calling process.

The process calling this function must not be impersonating a client.

See Also

CreatePrivateObjectSecurity, DestroyPrivateObjectSecurity, GENERIC_MAPPING, GetPrivateObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetFileSecurity, SetKernelObjectSecurity, SetUserObjectSecurity


SetProcessShutdownParameters

The SetProcessShutdownParameters function sets shutdown parameters for the currently calling process. This function sets a shutdown order for a process relative to the other processes in the system.

BOOL SetProcessShutdownParameters(

DWORD  dwLevel,	// shutdown priority
DWORD  dwFlags	// shutdown flags
);
Parameters

dwLevel

Specifies the shutdown priority for a process relative to other processes in the system. The system shuts down processes from high dwLevel values to low. The highest and lowest shutdown priorities are reserved for system components. This parameter must be in the following range of values:

Value	Meaning
000−0FF	System reserved last shutdown range.
100−1FF	Application reserved last shutdown range.
200−2FF	Application reserved "in between" shutdown range.
300−3FF	Application reserved first shutdown range.
400−4FF	System reserved first shutdown range.
All processes start at shutdown level 0x280.

dwFlags

Specifies a flags parameter. It can be the following value:

Value	Meaning
SHUTDOWN_NORETRY	Specifies whether to retry the shutdown if the specified time-out period expires. If this flag is specified, the system terminates the process without displaying a retry dialog box for the user.
Return Value

If the function is succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Applications running in the system security context do not get shut down by the operating system. They get notified of shutdown or logoff through the callback function installable via SetConsoleCtrlHandler. They also get notified in the order specified by the dwLevel parameter.

See Also

GetProcessShutdownParameters, SetConsoleCtrlHandler


SetProcessWindowStation  (preliminaryWindows NT)
SetProcessWindowStation  (preliminary−Windows NT)

The SetProcessWindowStation function assigns a window station to the calling process. This enables the process to access objects in the window station such as desktops, the clipboard, and global atoms. All subsequent operations on the window station use the access rights granted to hWinSta.

BOOL SetProcessWindowStation(

HWINSTA hWinSta	// handle of window station to assign to this process
);
Parameters

hWinSta

Identifies the window station to be assigned to the calling process. This handle is returned by the CreateWindowStation and OpenWindowStation functions.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateWindowStation, OpenWindowStation, SetThreadDesktop


SetProcessWorkingSetSize

The SetProcessWorkingSetSize function sets the minimum and maximum working set sizes for a specified process.

The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault. The size of the working set of a process is specified in bytes. The minimum and maximum working set sizes affect the virtual memory paging behavior of a process.

BOOL SetProcessWorkingSetSize(

HANDLE  hProcess,	// open handle to the process of interest
DWORD  dwMinimumWorkingSetSize,	// specifies minimum working set size
DWORD  dwMaximumWorkingSetSize	// specifies maximum working set size
);
Parameters

hProcess

An open handle to the process whose working set sizes will be set. The handle must have PROCESS_QUERY_INFORMATION access rights.

dwMinimumWorkingSetSize

Specifies a minimum working set size for the process. The virtual memory manager attempts to keep at least this much memory resident in the process whenever the process is active.

If both dwMinimumWorkingSetSize and dwMaximumWorkingSetSize have the value 0xffffffff, the function temporarily trims the working set of the specified process to zero. This essentially swaps the process out of physical RAM memory.

dwMaximumWorkingSetSize

Specifies a maximum working set size for the process. The virtual memory manager attempts to keep no more than this much memory resident in the process whenever the process is active and memory is in short supply.

If both dwMinimumWorkingSetSize and dwMaximumWorkingSetSize have the value 0xffffffff, the function temporarily trims the working set of the specified process to zero. This essentially swaps the process out of physical RAM memory.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. Call GetLastError to obtain extended error information.

Remarks

The working set of the specified process can be emptied by specifying the value 0xffffffff for both the minimum and maximum working set sizes.

If the values of either dwMinimumWorkingSetSize or dwMaximumWorkingSetSize are greater than the process' current working set sizes, the specified process must have the SE_INC_BASE_PRIORITY_PRIVILEGE privilege. Users in the Administrators and Power Users groups generally have this privilege.

The operating system allocates working set sizes on a first-come, first-served basis. For example, if an application successfully sets 40 megabytes as its minimum working set size on a 64-megabyte system, and a second application requests a 40-megabyte working set size, the operating system denies the second application's request.

Using the SetProcessWorkingSetSize function to set an application's minimum and maximum working set sizes does not guarantee that the requested memory will be reserved, or that it will remain resident at all times. When the application is idle, or a low-memory situation causes a demand for memory, the operating system can reduce the application's working set. An application can use the VirtualLock function to lock ranges of the application's virtual address space in memory; however, that can potentially degrade the performance of the system.

When you increase the working set size of an application, you are taking away physical memory from the rest of the system. This can degrade the performance of other applications and the system as a whole. It can also lead to failures of operations that require physical memory to be present; for example, creating processes, threads, and kernel pool. Thus, you must use the SetProcessWorkingSetSize function carefully. You must always consider the performance of the whole system when you are designing an application.

See Also

GetProcessWorkingSetSize, VirtualLock


SetProp

The SetProp function adds a new entry or changes an existing entry in the property list of the specified window. The function adds a new entry to the list if the specified character string does not exist already in the list. The new entry contains the string and the handle. Otherwise, the function replaces the string's current handle with the specified handle.

BOOL SetProp(

HWND  hwnd,	// handle of window
LPCTSTR  lpsz,	// atom or address of string
HANDLE  hData	// handle of data
);
Parameters

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.

Return Value

If the data handle and string are added to the property list, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Before destroying a window (that is, before processing the WM_DESTROY message), an application must remove all entries it has added to the property list. The application must use the RemoveProp function to remove the entries.

See Also

EnumProps, EnumPropsEx, GetProp, GlobalAddAtom, RemoveProp


SetRect

The SetRect function sets the coordinates of the specified rectangle. This is equivalent to assigning the left, top, right, and bottom arguments to the appropriate members of the RECT structure.

BOOL SetRect(

LPRECT  lprc,	// address of structure with rectangle to set
int  nLeft,	// left side
int  nTop,	// top side
int  nRight,	// right side
int  nBottom	// bottom side
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CopyRect, SetRectEmpty, RECT


SetRectEmpty

The SetRectEmpty function creates an empty rectangle in which all coordinates are set to zero.

BOOL SetRectEmpty(

LPRECT  lprc	// address of structure with rectangle set to empty
);
Parameters

lprc

Points to the RECT structure that contains the coordinates of the rectangle.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CopyRect, RECT, SetRect


SetRectRgn

The SetRectRgn function changes a region into a rectangular region with the specified coordinates.

BOOL SetRectRgn(

HRGN  hrgn,	// handle of region
int  nLeftRect,	// x-coordinate of upper-left corner of rectangle
int  nTopRect,	// y-coordinate of upper-left corner of rectangle
int  nRightRect,	// x-coordinate of lower-right corner of rectangle
int  nBottomRect	// y-coordinate of lower-right corner of rectangle
);
Parameters

hrgn

Identifies the region.

nLeftRect

Specifies the x-coordinate of the upper-left corner of the rectangular region.

nTopRect

Specifies the y-coordinate of the upper-left corner of the rectangular region.

nRightRect

Specifies the x-coordinate of the lower-right corner of the rectangular region.

nBottomRect

Specifies the y-coordinate of the lower-right corner of the rectangular region.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The region does not include the lower and right boundaries of the rectangle.

See Also

CreateRectRgn


SetResourceHandler

The SetResourceHandler function is not implemented in the Win32 API. Calculated resources do not work in the 32-bit environment.


SetROP2

The SetROP2 function sets the current foreground mix mode. GDI uses the foreground mix mode to combine pens and interiors of filled objects with the colors already on the screen. The foreground mix mode defines how colors from the brush or pen and the colors in the existing image are to be combined.

int SetROP2(

HDC  hdc,	// handle of device context
int  fnDrawMode	// drawing mode
);
Parameters

hdc

Identifies the device context.

fnDrawMode

Specifies the new mix mode. This parameter can be any one of the following values:

Mix mode	Description
R2_BLACK	Pixel is always 0.
R2_COPYPEN	Pixel is the pen color.
R2_MASKNOTPEN	Pixel is a combination of the colors common to both the screen and the inverse of the pen.
R2_MASKPEN	Pixel is a combination of the colors common to both the pen and the screen.
R2_MASKPENNOT	Pixel is a combination of the colors common to both the pen and the inverse of the screen.
R2_MERGENOTPEN	Pixel is a combination of the screen color and the inverse of the pen color.
R2_MERGEPEN	Pixel is a combination of the pen color and the screen color.
R2_MERGEPENNOT	Pixel is a combination of the pen color and the inverse of the screen color.
R2_NOP	Pixel remains unchanged.
R2_NOT	Pixel is the inverse of the screen color.
R2_NOTCOPYPEN	Pixel is the inverse of the pen color.
R2_NOTMASKPEN	Pixel is the inverse of the R2_MASKPEN color.
R2_NOTMERGEPEN	Pixel is the inverse of the R2_MERGEPEN color.
R2_NOTXORPEN	Pixel is the inverse of the R2_XORPEN color.
R2_WHITE	Pixel is always 1.
R2_XORPEN	Pixel is a combination of the colors in the pen and in the screen, but not in both.
Return Value

If the function succeeds, the return value specifies the previous mix mode.

If the function fails, the return value is zero.

Remarks

Mix modes define how GDI combines source and destination colors when drawing with the current pen. The mix modes are binary raster operation codes, representing all possible Boolean functions of two variables, using the binary operations AND, OR, and XOR (exclusive OR), and the unary operation NOT. The mix mode is for raster devices only; it is not available for vector devices.

See Also

GetROP2


SetScrollInfo  (preliminaryWindows NT)
SetScrollInfo  (preliminary−Windows NT)

The SetScrollInfo function sets the parameters of a scroll bar, including the minimum and maximum scrolling positions, the page size, and the position of the scroll box (thumb). The function also redraws the scroll bar, if requested.

int SetScrollInfo(

HWND  hwnd,	// handle of window with scroll bar
int  fnBar,	// scroll bar flag
LPSCROLLINFO  lpsi,	// pointer to structure with scroll parameters
BOOL  fRedraw	// redraw flag
);
Parameters

hwnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the fnBar parameter.

fnBar

Specifies the type of scroll bar for which to set parameters. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Sets the parameters of a scroll bar control. The hwnd parameter must be the handle of the scroll bar control.
SB_HORZ	Sets the parameters of the given window's standard horizontal scroll bar.
SB_VERT	Sets the parameters of the given window's standard vertical scroll bar.
lpsi

Points to a SCROLLINFO structure whose fMask member, upon entry to the function, specifies the scroll bar parameters to set.

The fMask member can be a combination of the following values:

Value	Meaning
SIF_DISABLENOSCROLL	Disables the scroll bar instead of removing it, if the scroll bar's new parameters make the scroll bar unnecessary.
SIF_PAGE	Sets the scroll page to the value specified in the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS	Sets the scroll position to the value specified in the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE	Sets the scroll range to the value specified in the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
fRedraw

Specifies whether the scroll bar is redrawn to reflect the changes to the scroll bar. If this parameter is TRUE, the scroll bar is redrawn, otherwise, it is not redrawn.

Return Value

The return value is the current position of the scroll box.

Remarks

The SetScrollInfo function performs range checking on the values specified by the nPage and nPos members of the SCROLLINFO structure. The nPage member must specify a value from 0 to nMax - nMin +1. The nPos member must specify a value between nMin and nMax - max(nPage  − 1, 0). If either value is beyond its range, the function sets it to a value that is just within the range.

See Also

GetScrollInfo, SCROLLINFO


SetScrollPos

The SetScrollPos function sets the position of the scroll box (thumb) in the specified scroll bar and, if requested, redraws the scroll bar to reflect the new position of the scroll box. The SetScrollPos function is provided for compatibility with Windows 3.x. Win32-based applications should use the SetScrollInfo function.

int SetScrollPos(

HWND  hwnd,	// handle of window with scroll bar
int  fnBar,	// scroll bar flag
int  nPos,	// new position of scroll box
BOOL  fRedraw	// redraw flag
);
Parameters

hwnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the fnBar parameter.

fnBar

Specifies the scroll bar to be set. This parameter can be one of the following values:

Value	Meaning
SB_CTL	Sets the position of the scroll box in a scroll bar control. The hwnd parameter must be the handle of the scroll bar control.
SB_HORZ	Sets the position of the scroll box in a window's standard horizontal scroll bar.
SB_VERT	Sets the position of the scroll box in a window's standard vertical scroll bar.
nPos

Specifies the new position of the scroll box. The position must be within the scrolling range. For more information about the scrolling range, see the SetScrollRange function.

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.

Return Value

If the function succeeds, the return value is the previous position of the scroll box.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

If the scroll bar is redrawn by a subsequent call to another function, setting the fRedraw parameter to FALSE is useful.

Because the messages that indicate scroll bar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data, applications that rely solely on those messages for position data have a practical maximum value of 65,535 for the SetScrollPos function's nPos parameter.

However, because the SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, GetScrollRange, ScrollDC, ScrollWindow, SetScrollRange


SetScrollRange

The SetScrollRange function sets the minimum and maximum position values for the specified scroll bar. It can also be used to hide or show a standard scroll bar.The SetScrollRange function is provided for compatibility with Windows 3.x. Win32-based applications should use the SetScrollInfo function.

BOOL SetScrollRange(

HWND  hwnd,	// handle of window with scroll bar
int  fnBar,	// scroll bar flag
int  nMinPos,	// minimum scrolling position
int  nMaxPos,	// maximum scrolling position
BOOL  fRedraw	// redraw flag
);
Parameters

hwnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the fnBar parameter.

fnBar

Specifies the 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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application 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 parameter values are zero). The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than the value of MAXLONG.

Because the messages that indicate scroll bar position, WM_HSCROLL and WM_VSCROLL, are limited to 16 bits of position data, applications that rely solely on those messages for position data have a practical maximum value of 65,535 for the SetScrollRange function's nMaxPos parameter.

However, because the SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, GetScrollRange, SetScrollPos


SetSecurityDescriptorDacl

The SetSecurityDescriptorDacl function sets information in a discretionary access-control list (ACL). If a discretionary ACL is already present in the security descriptor, it is replaced.

BOOL SetSecurityDescriptorDacl(

PSECURITY_DESCRIPTOR  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
);
Parameters

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 discretionary ACL in the security descriptor. If this parameter is TRUE, the function sets the SE_DACL_PRESENT flag in the SECURITY_DESCRIPTOR_CONTROL structure and uses the values in the 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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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

ACL, GetSecurityDescriptorDacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl


SetSecurityDescriptorGroup

The SetSecurityDescriptorGroup function sets the primary group information of an absolute-format security descriptor, replacing any primary group information already present in the security descriptor.

BOOL SetSecurityDescriptorGroup(

PSECURITY_DESCRIPTOR  psd,	// address of security descriptor
PSID  psidGroup,	// address of SID for group
BOOL  fGroupDefaulted	// flag for default
);
Parameters

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 a SID structure the function sets as the security descriptor's new primary group. The SID structure is referenced by, not copied into, the security descriptor. If this parameter is NULL, the function clears the security descriptor's primary group information. This marks the security descriptor as having no primary group.

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetSecurityDescriptorGroup, InitializeSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorDacl, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl, SID


SetSecurityDescriptorOwner

The SetSecurityDescriptorOwner function sets the owner information of an absolute-format security descriptor. It replaces any owner information already present in the security descriptor.

BOOL SetSecurityDescriptorOwner(

PSECURITY_DESCRIPTOR  psd,	// address of security descriptor
PSID  psidOwner,	// address of SID for owner
BOOL  fOwnerDefaulted	// flag for default
);
Parameters

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 a SID structure the function sets as the security descriptor's new primary owner. The SID structure is referenced by, not copied into, the security descriptor. If this parameter is NULL, the function clears the security descriptor's owner information. This marks the security descriptor as having no owner.

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetSecurityDescriptorOwner, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorSacl, SID


SetSecurityDescriptorSacl

The SetSecurityDescriptorSacl function sets information in a system access-control list (ACL). If there is already a system ACL present in the security descriptor, it is replaced.

BOOL SetSecurityDescriptorSacl(

PSECURITY_DESCRIPTOR  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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

ACL, GetSecurityDescriptorSacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SECURITY_DESCRIPTOR, SECURITY_DESCRIPTOR_CONTROL, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner


SetService

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

INT SetService(

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

dwNameSpace

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

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

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

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

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

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

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

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

lpServiceAsyncInfo

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

lpdwStatusFlags

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

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

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

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

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

GetService, SERVICE_INFO, SERVICE_TYPE_INFO_ABS


SetServiceBits

The SetServiceBits function registers a service's service type with the Service Control Manager and the Server service. The Server service can then announce the registered service type as one it currently supports. The LAN Manager functions NetServerGetInfo and NetServerEnum obtain a specified machine's supported service types.

A service type is represented as a set of bit flags; the SetServiceBits function sets or clears combinations of those bit flags.

BOOL SetServiceBits (

SERVICE_STATUS_HANDLE  hServiceStatus,	// service status handle
DWORD  dwServiceBits,	// service type bits to set or clear
BOOL  bSetBitsOn,	// flag to set or clear the service type bits
BOOL bUpdateImmediately	// flag to announce server type immediately
);
Parameters

hServiceStatus

A handle to the Service Control Manager's status information structure for a service. A service obtains a SERVICE_STATUS_HANDLE value by calling the RegisterServiceCtrlHandler function. It is the service's handle for making calls to the Service Control Manager.

dwServiceBits

A set of bit flags that specifies a service type.

Certain bit flags (0xC00F3F7B) are reserved for use by Microsoft. The SetServiceBits function fails with the error ERROR_INVALID_DATA if any of these bit flags are set in dwServiceBits. There are 18 of these bit flags:

Bit Flag Constant	Value
SV_TYPE_WORKSTATION	0x00000001
SV_TYPE_SERVER	0x00000002
SV_TYPE_DOMAIN_CTRL	0x00000008
SV_TYPE_DOMAIN_BAKCTRL	0x00000010
SV_TYPE_TIME_SOURCE	0x00000020
SV_TYPE_AFP	0x00000040
SV_TYPE_DOMAIN_MEMBER	0x00000100
SV_TYPE_PRINTQ_SERVER	0x00000200
SV_TYPE_DIALIN_SERVER	0x00000400
SV_TYPE_XENIX_SERVER	0x00000800
SV_TYPE_SERVER_UNIX	0x00000800
SV_TYPE_NT	0x00001000
SV_TYPE_WFW	0x00002000
SV_TYPE_POTENTIAL_BROWSER	0x00010000
SV_TYPE_BACKUP_BROWSER	0x00020000
SV_TYPE_MASTER_BROWSER	0x00040000
SV_TYPE_DOMAIN_MASTER	0x00080000
SV_TYPE_LOCAL_LIST_ONLY	0x40000000
SV_TYPE_DOMAIN_ENUM	0x80000000
Certain bit flags (0x00300084) are defined by Microsoft, but are not specifically reserved for systems software. There are four of these bit flags:

Bit Flag Constant	Value
SV_TYPE_SV_TYPE_SQLSERVER	0x00000004
SV_TYPE_NOVELL	0x00000080
SV_TYPE_DOMAIN_CTRL	0x00100000
SV_TYPE_DOMAIN_BAKCTRL	0x00200000
Certain bit flags (0x3FC0C000) are not defined by Microsoft, and their use is not coordinated by Microsoft. Developers of applications that use these bits should be aware that other applications may also use them, thus creating a conflict. There are 10 of these bit flags:

Value	Value
0x00004000	0x02000000
0x00008000	0x04000000
0x00400000	0x08000000
0x00800000	0x10000000
0x01000000	0x20000000
bSetBitsOn

A BOOLEAN that specifies whether the function is to set or clear the bit flags that are set in dwServiceBit. The value TRUE specifies that the bits are to be set; FALSE specifies clearing.

bUpdateImmediately

A BOOLEAN that specifies whether the Server service is to perform an immediate update, announcing the new service type. The value TRUE specifies an immediate update; FALSE specifies otherwise.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

NetServerGetInfo, NetServerEnum,RegisterServiceCtrlHandler, SetServiceStatus


SetServiceObjectSecurity

The SetServiceObjectSecurity function sets the security descriptor of a service object.

BOOL SetServiceObjectSecurity(

SC_HANDLE  schService,	// handle of service
SECURITY_INFORMATION  fdwSecurityInfo,	// type of security information requested
PSECURITY_DESCRIPTOR  psdSecurityDesc	// address of security descriptor
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED
	The specified handle was not opened with the required access, or the calling process is not the owner of the object.
ERROR_INVALID_HANDLE
	The specified handle is invalid.
ERROR_INVALID_PARAMETER
	The specified security information or security descriptor is invalid.
ERROR_SERVICE_MARKED_FOR_DELETE
	The specified service has been marked for deletion.
Remarks

The SetServiceObjectSecurity function sets the specified portions of the service object's security descriptor, based on the information specified in the 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


SetServiceStatus

The SetServiceStatus function updates the service control manager's status information for the calling service.

BOOL SetServiceStatus(

SERVICE_STATUS_HANDLE  sshServiceStatus,	// service status handle
LPSERVICE_STATUS  lpssServiceStatus	// address of status structure
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_INVALID_DATA	The specified service status structure is invalid.
Remarks

A Win32 service's ServiceMain function first calls the RegisterServiceCtrlHandler function to get the service's SERVICE_STATUS_HANDLE. Then it immediately calls the SetServiceStatus function to notify the service control manager of its SERVICE_START_PENDING status.

When a Win32 service receives a control request, the service's Handler function must call this function, even if the service's status did not change. A service can also use this function at any time and by any thread of the service to notify the service control manager of status changes. Examples of such unsolicited status updates include:

•	Checkpoint updates that occur when the service is in transition from one state to another (that is, SERVICE_START_PENDING).

•	An update made necessary by the expected occurrence of a fatal error that causes the service to stop.

A service can call this function only after it has called RegisterServiceCtrlHandler to get a service status handle.

See Also

Handler, RegisterServiceCtrlHandler, SERVICE_STATUS, ServiceMain, SetServiceBits


setsockopt

The Windows Sockets setsockopt function sets a socket option.

int setsockopt (

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

s

A descriptor identifying a socket.

level

The level at which the option is defined; the only supported levels are SOL_SOCKET and IPPROTO_TCP.

optname

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

optval

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

optlen

The size of the optval buffer.

Return Value

If the function succeeds, setsockopt returns zero.

If the function fails, a value of SOCKET_ERROR is returned. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEFAULT	The optval parameter is not in a valid part of the process address space.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEINVAL	The level parameter is not valid, or the information in optval is not valid.
WSAENETRESET	Connection has timed out when SO_KEEPALIVE is set.
WSAENOPROTOOPT	The option is unknown or unsupported. In particular, SO_BROADCAST is not supported on sockets of type SOCK_STREAM, while SO_DONTLINGER, SO_KEEPALIVE, SO_LINGER and SO_OOBINLINE are not supported on sockets of type SOCK_DGRAM.
WSAENOTCONN	Connection has been reset when SO_KEEPALIVE is set.
WSAENOTSOCK	The descriptor is not a socket.
Remarks

The setsockopt function sets the current value for a socket option associated with a socket of any type, in any state. Although options may exist at multiple protocol levels, this specification only defines options that exist at the uppermost "socket" level. Options affect socket operations, such as whether expedited data is received in the normal data stream, whether broadcast messages can be sent on the socket, and so on.

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

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

struct linger {

int    l_onoff;

int    l_linger;

}

To enable SO_LINGER, the application should set l_onoff to a nonzero value, set l_linger to zero or the desired timeout (in seconds), and call setsockopt. To enable SO_DONTLINGER (i.e. disable SO_LINGER) l_onoff should be set to zero and setsockopt should be called.

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

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

The TCP_NODELAY option disables the Nagle algorithm. The Nagle algorithm is used to reduce the number of small packets sent by a host by buffering unacknowledged send data until a full-size packet can be sent. However, for some applications this algorithm can impede performance, and TCP_NODELAY can be used to turn it off. You should not set TCP_NODELAY unless the impact of doing so is well understood and desired, since setting TCP_NODELAY can have a significant negative impact of network performance. TCP_NODELAY is the only supported socket option that uses level IPPROTO_TCP; all other options use level SOL_SOCKET.

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

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

Value	Type	Meaning
SO_BROADCAST	BOOL	Allow transmission of broadcast messages on the socket.
SO_DEBUG	BOOL	Record debugging information.
SO_DONTLINGER	BOOL	Don't block close waiting for unsent data to be sent. Setting this option is equivalent to setting SO_LINGER with l_onoff set to zero.
SO_DONTROUTE	BOOL	Don't route: send directly to interface.
SO_KEEPALIVE	BOOL	Send keepalive messages.
SO_LINGER	struct linger FAR *	Linger on close if unsent data is present.
SO_OOBINLINE	BOOL	Receive out-of-band data in the normal data stream.
SO_RCVBUF	int	Specify buffer size for receives.
SO_REUSEADDR	BOOL	Allow the socket to be bound to an address that is already in use. (See bind.)
SO_SNDBUF	int	Specify buffer size for sends.
TCP_NODELAY	BOOL	Disables the Nagle algorithm for send coalescing.
The following BSD options are not supported for setsockopt.

Value	Type	Meaning
SO_ACCEPTCONN	BOOL	Socket is listening
SO_ERROR	int	Get error status and clear
SO_RCVLOWAT	int	Receive low-water mark
SO_RCVTIMEO	int	Receive timeout
SO_SNDLOWAT	int	Send low-water mark
SO_SNDTIMEO	int	Send timeout
SO_TYPE	int	Type of the socket
IP_OPTIONS		Set options field in IP header.
See Also

bind, getsockopt, ioctlsocket, socket, WSAAsyncSelect, WSAStartup


SetSoundNoise

The SetSoundNoise function has been deleted.

See Also

Beep, MessageBeep


SetStdHandle

The SetStdHandle function is used to set the handle for the standard input, standard output, or standard error device. The specified handle can be used by subsequent calls to the GetStdHandle function to refer to the input, output, or error device.

BOOL SetStdHandle(

DWORD  IDStdHandle,	// input, output, or error device
HANDLE  hHandle	// handle to be a standard handle
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The standard handles of a process may have been redirected by a call to SetStdHandle, in which case GetStdHandle will return the redirected handle. If the standard handles have been redirected, you can specify the CONIN$ value in a call to the CreateFile function to get a handle of a console's input buffer. Similarly, you can specify the CONOUT$ value to get a handle of the console's active screen buffer.

See Also

CreateFile, GetStdHandle


SetStretchBltMode

The SetStretchBltMode function sets the bitmap stretching mode in the specified device context.

int SetStretchBltMode(

HDC  hdc,	// handle of device context
int  iStretchMode	// bitmap stretching mode
);
Parameters

hdc

Identifies the device context.

iStretchMode

Specifies the stretching mode. It can be one of the following values:

Value	Description
BLACKONWHITE	Performs a Boolean AND operation using the color values for the eliminated and existing pixels. If the bitmap is a monochrome bitmap, this mode preserves black pixels at the expense of white pixels.
COLORONCOLOR	Deletes the pixels. This mode deletes all eliminated lines of pixels without trying to preserve their information.
HALFTONE	Maps pixels from the source rectangle into blocks of pixels in the destination rectangle. The average color over the destination block of pixels approximates the color of the source pixels.
	After setting the HALFTONE stretching mode, an application must call the SetBrushOrgEx function to set the brush origin. If it fails to do so, brush misalignment occurs.
STRETCH_ANDSCANS	Windows 95: Same as BLACKONWHITE.
STRETCH_DELETESCANS	Windows 95: Same as COLORONCOLOR.
STRETCH_HALFTONE	Windows 95: Same as HALFTONE.
STRETCH_ORSCANS	Windows 95: Same as WHITEONBLACK.
WHITEONBLACK	Performs a Boolean OR operation using the color values for the eliminated and existing pixels. If the bitmap is a monochrome bitmap, this mode preserves white pixels at the expense of black pixels.
Return Value

If the function succeeds, the return value is the previous stretching mode.

If the function fails, the return value is zero.

Remarks

The stretching mode defines how Windows combines rows or columns of a bitmap with existing pixels on a display device when an application calls the StretchBlt function.

The BLACKONWHITE (STRETCH_ANDSCANS) and WHITEONBLACK (STRETCH_ORSCANS) modes are typically used to preserve foreground pixels in monochrome bitmaps. The COLORONCOLOR (STRETCH_DELETESCANS) mode is typically used to preserve color in color bitmaps.

The HALFTONE mode requires more processing of the source image than the other three modes; it is slower than the others but produces higher quality images. Also note that SetBrushOrgEx must be called after setting the HALFTONE mode to avoid brush misalignment.

Additional stretching modes might also be available depending on the capabilities of the device driver.

See Also

SetBrushOrgEx, StretchBlt


SetSwapAreaSize

The SetSwapAreaSize function is obsolete. It has no meaning in the 32-bit environment.


SetSysColors

The SetSysColors function sets the colors for one or more display elements. Display elements are the various parts of a window and the Windows display that appear on the system display screen.

BOOL WINAPI SetSysColors(

int  cDspElements,	// number of elements to change
CONST INT  *lpnDspElements,	// address of array of elements
CONST COLORREF  *lpdwRgbValues	// address of array of RGB values
);
Parameters

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. For a list of display elements, see the GetSysColor function.

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The SetSysColors function sends a WM_SYSCOLORCHANGE message to all windows to inform them of the change in color. It also directs Windows to repaint the affected portions of all currently visible windows.

The SetSysColors function changes the current Windows session only. The new colors are not saved when Windows terminates.

See Also

GetSysColor


SetSysModalWindow

The SetSysModalWindow function is not implemented in the Win32 API. The new input model does not allow for System Modal windows.


SetSystemCursor

The SetSystemCursor function replaces the contents of the system cursor specified by dwCursorId with the contents of the cursor specified by hCursor, and then destroys hCursor. This function lets an application customize the system cursors.

BOOL SetSystemCursor (

HCURSOR  hCursor,	// set specified system cursor to this cursor's contents,  // then destroy this
DWORD  dwCursorID	// system cursor specified by its identifier
);
Parameters

hCursor

Handle to a cursor. The function replaces the contents of the system cursor specified by dwCursorID with the contents of the cursor handled by hCursor. Then the function destroys hCursor by calling DestroyCursor(hCursor).

dwCursorID

A system cursor identifier. The function replaces the contents of this system cursor with the contents of the cursor handled by hCursor.

Following is a list of system cursor identifiers:

Value	Description
OCR_NORMAL	normal arrow cursor
OCR_IBEAM	I-beam cursor
OCR_WAIT	larger hourglass cursor
OCR_CROSS	crosshair cursor
OCR_UP	up arrow cursor
OCR_SIZE	size cursor
OCR_ICON	icon cursor
OCR_SIZENWSE	NW to SE sizing cursor
OCR_SIZENESW	NE to SW sizing cursor
OCR_SIZEWE	horizontal sizing cursor
OCR_SIZENS	vertical sizing cursor
OCR_SIZEALL	horizontal and vertical sizing cursor
OCR_SIZENO	international no symbol cursor
OCR_APPSTARTING	smaller hourglass with arrow cursor
Return Value

If the function succeeds, the return value is TRUE.

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

See Also

DestroyCursor, LoadCursor, LoadCursorFromFile, SetCursor


SetSystemPaletteUse

The SetSystemPaletteUse function allows an application to specify whether the system palette contains 2 or 20 static colors. The default system palette contains 20 static colors. (Static colors cannot be changed when an application realizes a logical palette.)

UINT SetSystemPaletteUse(

HDC  hdc,	// handle of device context
UINT  uUsage	// palette-usage flag
);
Parameters

hdc

Identifies the device context. This device context must refer to a device that supports color palettes.

uUsage

Specifies the new use of the system palette. This parameter can be one of the following values:

Value	Meaning
SYSPAL_NOSTATIC	The system palette contains two static colors (black and white).
SYSPAL_STATIC	The system palette contains static colors that will not change when an application realizes its logical palette.
Return Value

If the function succeeds, the return value is the previous usage of the system palette (it can be either SYSPAL_NOSTATIC or SYSPAL_STATIC).

If the function fails, the return value is SYSPAL_ERROR. To get extended error information, call GetLastError.

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

When an application window moves to the foreground and the SYSPAL_NOSTATIC value is set, the application must call the GetSysColor function to save the current system colors setting. It must also call SetSysColors to set reasonable values using only black and white. When the application returns to the background or terminates, the previous system colors must be restored.

If the function returns SYSPAL_ERROR, the specified device context is invalid or does not support color palettes.

An application must call this function only when its window is maximized and has the input focus.

If an application calls SetSystemPaletteUse with uUsage set to SYSPAL_NOSTATIC, Windows continues to set aside two entries in the system palette for pure white and pure black, respectively.

After calling this function with uUsage set to SYSPAL_NOSTATIC, an application must take the following steps:

1.	Realize the logical palette.

2.	Call the GetSysColor function to save the current system-color settings.

3.	Call the SetSysColors function to set the system colors to reasonable values using black and white. For example, adjacent or overlapping items (such as window frames and borders) should be set to black and white, respectively.

4.	Send the WM_SYSCOLORCHANGE message to other top-level windows to allow them to be redrawn with the new system colors.

When the application's window loses focus or closes, the application must perform the following steps:

1.	Call SetSystemPaletteUse with the uUsage parameter set to SYSPAL_STATIC.

2.	Realize the logical palette.

3.	Restore the system colors to their previous values.

4.	Send the WM_SYSCOLORCHANGE message.

See Also

GetDeviceCaps, GetSysColor, SetSysColors


SetSystemPowerState  (preliminaryWindows 95)
SetSystemPowerState  (preliminary−Windows 95)

The SetSystemPowerState function suspends the system by shutting power down. Depending on the ForceFlag parameter, the function either suspends operation immediately or requests permission from all applications and device drivers before doing so.

BOOL SetSystemPowerState(

BOOL  fSuspend,
BOOL  fForce
);
Parameters

fSuspend

Suspension technique. If TRUE, the system suspends using RAM-alive technique. Otherwise, suspends using hibernate technique.

fForce

Forced suspension. If TRUE, the function sends a PB_APMSUSPEND message to each application and driver, then immediately suspends operation. If FALSE, the function sends a PB_APMQUERYSUSPEND message to each application to request permission to suspend operation.

Return Value

If power has been suspended and subsequently restored, the return value is TRUE.

If the system did not suspend, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

If any application or driver denies permission to suspend operation, the function sends a PB_APMQUERYSUSPENDFAILED message to each application and driver. If power is suspended, this function returns only after system operation is resumed and related WM_POWERBROADCAST messages have been sent to all applications and drivers.

See Also

PB_APMQUERYSUSPEND, PB_APMQUERYSUSPENDFAILED, PB_APMSUSPEND, WM_POWERBROADCAST


SetSystemTime

The SetSystemTime function sets the current system time and date. The system time is expressed in Coordinated Universal Time (UTC).

BOOL SetSystemTime(

CONST SYSTEMTIME *  lpst	// address of system time to set
);
Parameters

lpst

Points to a SYSTEMTIME structure that contains the current system date and time.

The wDayOfWeek member of the SYSTEMTIME structure is ignored.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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

See Also

AdjustTokenPrivileges, GetSystemTime, SetSystemTimeAdjustment, SYSTEMTIME, SystemTimeToTzSpecificLocalTime


SetSystemTimeAdjustment

The SetSystemTimeAdjustment function tells the system to enable or disable periodic time adjustments to its time of day clock. Such time adjustments are used to synchronize the time of day with some other source of time information. When periodic time adjustments are enabled, they are applied at each clock interrupt.

BOOL SetSystemTimeAdjustment(

DWORD  dwTimeAdjustment,	// size, in 100-nanosecond units, of a periodic time adjustment
PBOOL  bTimeAdjustmentDisabled	// whether periodic time adjustment is to be disabled or enabled
);
Parameters

dwTimeAdjustment

Specifies the number of 100-nanosecond units added to the time-of-day clock at each clock interrupt if periodic time adjustment is enabled.

bTimeAdjustmentDisabled

Specifies the time adjustment mode that the system is to use. Periodic system time adjustments can be disabled or enabled.

A value of TRUE specifies that periodic time adjustment is to be disabled. The system is free to adjust time of day using its own internal mechanisms. The value of dwTimeAdjustment is ignored. The system's internal adjustment mechanisms may cause the time-of-day clock to jump noticeably when adjustments are made.

A value of FALSE specifies that periodic time adjustment is to be enabled, and will be used to adjust the time-of-day clock. The system will not interfere with the time adjustment scheme, and will not attempt to synchronize time of day on its own. The system will add the value of dwTimeAdjustment to the time of day at each clock interrupt.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. One way the function can fail is if the caller does not possess the SE_SYSTEMTIME_NAME privilege.

Remarks

The GetSystemTimeAdjustment and SetSystemTimeAdjustment functions support algorithms that synchronize the time-of-day clock, reported via GetSystemTime and GetLocalTime, with another time source using a periodic time adjustment.

The SetSystemTimeAdjustment function supports two modes of time synchronization: time-adjustment − disabled and time-adjustment − enabled.

In the first mode, bTimeAdjustmentDisabled is set to FALSE.  At each clock interrupt, the system adds the value of dwTimeAdjustment to the time of day. The clock interrupt rate may be determined by calling GetSystemTimeAdjustment, and looking at the returned value of the DWORD value pointed to by lpTimeIncrement.

In the second mode, bTimeAdjustmentDisabled is set to TRUE.  At each clock interrupt, the system adds the interval between clock interrupts to the time of day. No adjustment to that interval is made. The system is free to periodically refresh the time-of-day clock using other techniques. Such other techniques may cause the time-of-day clock to jump noticeably when adjustments are made.

An application must have system-time privilege (the SE_SYSTEMTIME_NAME privilege) for this function to succeed. The SE_SYSTEMTIME_NAME privilege is disabled by default. Use the AdjustTokenPrivileges function to enable the privilege before calling SetSystemTimeAdjustment, and then to disable the privilege after the SetSystemTimeAdjustment call.

See Also

AdjustTokenPrivileges, GetSystemTimeAdjustment, SetLocalTime, SetSystemTime, SystemTimeToTzSpecificLocalTime


SetTapeParameters

The SetTapeParameters function either specifies the block size of a tape or configures the tape device.

DWORD SetTapeParameters(

HANDLE  hDevice,	// handle of open device
DWORD  dwOperation,	// type of information to set
LPVOID  lpTapeInformation	// address of buffer with information to set
);
Parameters

hDevice

Identifies the device for which to set configuration information. This handle is created by using the CreateFile function.

dwOperation

Specifies the type of information to set. This parameter must be one of the following values:

Value	Description
SET_TAPE_MEDIA_INFORMATION	Sets the tape-specific information specified by the lpTapeInformation parameter.
GET_TAPE_DRIVE_INFORMATION	Sets the device-specific information specified by lpTapeInformation.
lpTapeInformation

Points to a structure that contains the information to set. If the dwOperation parameter is SET_TAPE_MEDIA_INFORMATION, lpTapeInformation points to a TAPE_SET_MEDIA_PARAMETERS structure.

If dwOperation is SET_TAPE_DRIVE_INFORMATION, lpTapeInformation points to a TAPE_SET_DRIVE_PARAMETERS structure.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes:

Error	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
See Also

GetTapeParameters, TAPE_SET_DRIVE_PARAMETERS, TAPE_SET_MEDIA_PARAMETERS


SetTapePosition

The SetTapePosition sets the tape position on the specified device.

DWORD SetTapePosition(

HANDLE  hDevice,	// handle of open device
DWORD  dwPositionMethod,	// type of positioning to perform
DWORD  dwPartition,	// new tape partition
DWORD  dwOffsetLow,	// low-order 32 bits of tape position
DWORD  dwOffsetHigh,	// high-order 32 bits of tape position
BOOL  bImmediate	// return after operation begins
);
Parameters

hDevice

Identifies the device on which to set the tape position. This handle is created by using the CreateFile function.

dwPositionMethod

Specifies the type of positioning to perform. This parameter must be one of the following values:

Value	Meaning
TAPE_ABSOLUTE_BLOCK	Moves the tape to the device-specific block address specified by the dwOffsetLow and dwOffsetHigh parameters. The dwPartition parameter is ignored.
TAPE_LOGICAL_BLOCK	Moves the tape to the block address specified by dwOffsetLow and dwOffsetHigh in the partition specified by dwPartition.
TAPE_REWIND	Moves the tape to the beginning of the current partition. The dwPartition, dwOffsetLow, and dwOffsetHigh parameters are ignored.
TAPE_SPACE_END_OF_DATA	Moves the tape to the end of the data on the partition specified by dwPartition.
TAPE_SPACE_FILEMARKS	Moves the tape forward (or backward) the number of filemarks specified by dwOffsetLow and dwOffsetHigh in the current partition. The dwPartition parameter is ignored.
TAPE_SPACE_RELATIVE_BLOCKS	Moves the tape forward (or backward) the number of blocks specified by dwOffsetLow and dwOffsetHigh in the current partition. The dwPartition parameter is ignored.
TAPE_SPACE_SEQUENTIAL_FMKS	Moves the tape forward (or backward) to the first occurrence of n filemarks in the current partition, where n is the number specified by dwOffsetLow and dwOffsetHigh. The dwPartition parameter is ignored.
TAPE_SPACE_SEQUENTIAL_SMKS	Moves the tape forward (or backward) to the first occurrence of n setmarks in the current partition, where n is the number specified by dwOffsetLow and dwOffsetHigh. The dwPartition parameter is ignored.
TAPE_SPACE_SETMARKS	Moves the tape forward (or backward) the number of setmarks specified by dwOffsetLow and dwOffsetHigh in the current partition. The dwPartition parameter is ignored.
dwPartition

Specifies the partition to position within. If dwPartition is zero, the current partition is used. Partitions are numbered logically from 1 through n, where 1 is the first partition on the tape and n is the last.

dwOffsetLow

Specifies the low-order 32 bits of the block address or count for the position operation specified by the dwPositionMethod parameter.

dwOffsetHigh

Specifies the high-order 32 bits of the block address or count for the position operation specified by the dwPositionMethod parameter. If the high-order 32 bits are not required, this parameter should be zero.

bImmediate

Indicates whether to return as soon as the move operation begins. If this parameter is TRUE, the function returns immediately; if FALSE, the function does not return until the move operation has been completed.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes:

Error	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

If the offset specified by dwOffsetLow and dwOffsetHigh specifies the number of blocks, filemarks, or setmarks to move, a positive offset moves the tape forward to the end of the last block, filemark, or setmark. A negative offset moves the tape backward to the beginning of the last block, filemark, or setmark. If the offset is zero, the tape does not move.

To obtain information about the status, capabilities, and capacities of tape drives and media, call the GetTapeParameters function.

See Also

CreateFile, GetTapeParameters, GetTapePosition


SetTextAlign

The SetTextAlign function sets the text-alignment flags for the specified device context.

UINT SetTextAlign(

HDC  hdc,	// handle of device context
UINT  fMode	// text-alignment flag
);
Parameters

hdc

Identifies the device context.

fMode

Specifies the text alignment by using a mask of the values in the following list. Only one flag can be chosen from those that affect horizontal and vertical alignment. In addition, only one of the two flags that alter the current position can be chosen.

Value	Meaning
TA_BASELINE	The reference point will be on the base line of the text.
TA_BOTTOM	The reference point will be on the bottom edge of the bounding rectangle.
TA_TOP	The reference point will be on the top edge of the bounding rectangle.
TA_CENTER	The reference point will be aligned horizontally with the center of the bounding rectangle.
TA_LEFT	The reference point will be on the left edge of the bounding rectangle.
TA_RIGHT	The reference point will be on the right edge of the bounding rectangle.
TA_NOUPDATECP	The current position is not updated after each text output call. The reference point is passed to the text output function.
TA_RTLREADING	Windows 95 only: The text is laid out in right to left reading order, as opposed to the default left to right order. This applies only when the font selected into the device context is either Hebrew or Arabic.
TA_UPDATECP	The current position is updated after each text output call. The current position is used as the reference point.
When the current font has a vertical default base line, as with Kanji, the following values must be used instead of TA_BASELINE and TA_CENTER:

Value	Meaning
VTA_BASELINE	The reference point will be on the base line of the text.
VTA_CENTER	The reference point will be aligned vertically with the center of the bounding rectangle.
The default values are TA_LEFT, TA_TOP, and TA_NOUPDATECP.

Return Value

If the function succeeds, the return value is the previous text-alignment setting.

If the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

Remarks

The TextOut and ExtTextOut functions use the text-alignment flags to position a string of text on a display or other device. The flags specify the relationship between a reference point and a rectangle that bounds the text. The reference point is either the current position or a point passed to a text output function.

The rectangle that bounds the text is formed by the character cells in the text string.

See Also

ExtTextOut, TextOut


SetTextCharacterExtra

The SetTextCharacterExtra function sets the intercharacter spacing. Intercharacter spacing is added to each character, including break characters, when Windows writes a line of text.

int SetTextCharacterExtra(

HDC  hdc,	// handle of device context
int  nCharExtra	// extra-space value
);
Parameters

hdc

Identifies the device context.

nCharExtra

Specifies the amount of extra space, in logical units, to be added to each character. If the current mapping mode is not MM_TEXT, the nCharExtra parameter is transformed and rounded to the nearest pixel.

Return Value

If the function succeeds, the return value is the previous intercharacter spacing.

If the function fails, the return value is 0x80000000.

See Also

DrawText, GetTextCharacterExtra, TextOut


SetTextColor

The SetTextColor function sets the text color for the specified device context to the specified color.

COLORREF SetTextColor(

HDC  hdc,	// handle of device context
COLORREF  crColor	// text color
);
Parameters

hdc

Identifies the device context.

crColor

Specifies the color of the text.

Return Value

If the function succeeds, the return value is a color reference for the previous text color.

If the function fails, the return value is CLR_INVALID. To get extended error information, call GetLastError.

Remarks

The text color is used to draw the face of each character written by the TextOut and ExtTextOut functions. The text color is also used in converting bitmaps from color to monochrome and vice versa.

See Also

BitBlt, ExtTextOut, RGB, SetBkColor, StretchBlt, TextOut


SetTextJustification

The SetTextJustification function specifies the amount of space Windows should add to the break characters in a string of text. The space is added when an application calls the TextOut or ExtTextOut functions.

BOOL SetTextJustification(

HDC  hdc,	// handle of device context
int  nBreakExtra,	// length of extra space, in logical units
int  nBreakCount	// count of space characters in line of text
);
Parameters

hdc

Identifies the device context.

nBreakExtra

Specifies the total extra space, in logical units, to be added to the line of text. If the current mapping mode is not MM_TEXT, the value identified by the nBreakExtra parameter is transformed and rounded to the nearest pixel.

nBreakCount

Specifies the number of break characters in the line.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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


SetThreadAffinityMask

The SetThreadAffinityMask function sets a processor affinity mask for a specified thread.

A thread affinity mask is a bit vector in which each bit represents the processors that a thread is allowed to run on.

A thread affinity mask must be a proper subset of the process affinity mask for the containing process of a thread. A thread is only allowed to run on the processors its process is allowed to run on.

DWORD SetThreadAffinityMask (

HANDLE  hThread,	// handle to the thread of interest
DWORD  dwThreadAffinityMask	// a thread affinity mask
);
Parameters

hThread

A handle to the thread whose affinity mask the function sets. This handle must have THREAD_SET_INFORMATION access.

dwThreadAffinityMask

Windows 95: This value must be 1.

Windows NT: Specifies an affinity mask for the thread.

Return Value

If the function succeeds, the return value is nonzero.

Windows 95: The return value is 1. To succeed, hThread must be valid and dwThreadAffinityMask must be 1.

Windows NT: The return value is the thread's previous affinity mask.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

See Also

GetProcessAffinityMask


SetThreadContext

The SetThreadContext function sets the context in the specified thread.

BOOL SetThreadContext(

HANDLE  hThread,	// handle of thread with context
CONST CONTEXT *  lpContext	// address of context structure
);
Parameters

hThread

Identifies an open handle of a thread whose context is to be written to. 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 specified are silently set to the correct value. This includes bits in the CPU status register that specify the privileged processor mode, global enabling bits in the debugging register, and other states that must be controlled by the operating system.

Return Value

If the context was set, the return value is TRUE.

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

Remarks

The function allows the selective context to be set based on the value of the ContextFlags member of the context structure. The thread handle identified by the hThread parameter is typically being debugged, but the function can also operate even when it is not being debugged.

See Also

CONTEXT, GetThreadContext


SetThreadDesktop  (preliminaryWindows NT)
SetThreadDesktop  (preliminary−Windows NT)

The SetThreadDesktop function assigns a desktop to the calling thread. All subsequent operations on the desktop use the access rights granted to hDesk.

BOOL SetThreadDesktop(

HDESK hDesk	// handle of the desktop to assign to this thread
);
Parameters

hDesk

Identifies the desktop to be assigned to the calling thread. This handle is returned by the CreateDesktop, GetThreadDesktop, and OpenDesktop functions.

This function will fail if the calling thread has any windows or hooks on its current desktop (unless hDesk is a handle to the current desktop).

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateDesktop, GetThreadDesktop, OpenDesktop, SetProcessWindowStation


SetThreadLocale

The SetThreadLocale function sets the calling thread's current locale.

BOOL SetThreadLocale (

LCID  Locale	// locale identifier
);
Parameters

Locale

Specifies the new locale for the calling thread. This parameter can be a locale identifier created by the MAKELCID macro, or one of the following predefined values:

LOCALE_SYSTEM_DEFAULT	Default system locale.
LOCALE_USER_DEFAULT	Default user locale.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

When a thread is created, it is given the system default thread locale. The system reads the system default thread locale from the registry when the system boots. This system default can be modified for future process and thread creation using Control Panel's International application.

See Also

GetThreadLocale, GetSystemDefaultLCID, GetUserDefaultLCID


SetThreadPriority

The SetThreadPriority function sets the priority value for the specified thread. This value, together with the priority class of the thread's process, determines the thread's base priority level.

BOOL SetThreadPriority(

HANDLE  hThread,	// handle to the thread
int  nPriority	// thread priority level
);
Parameters

hThread

Identifies the thread. 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_ABOVE_NORMAL	Indicates 1 point above normal priority for the priority class.
THREAD_PRIORITY_BELOW_NORMAL	Indicates 1 point below normal priority for the priority class.
THREAD_PRIORITY_HIGHEST	Indicates 2 points above normal priority for the priority class.
THREAD_PRIORITY_IDLE	Indicates a base priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 16 for REALTIME_PRIORITY_CLASS processes.
THREAD_PRIORITY_LOWEST	Indicates 2 points below normal priority for the priority class.
THREAD_PRIORITY_NORMAL	Indicates normal priority for the priority class.
THREAD_PRIORITY_TIME_CRITICAL	Indicates a base priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 31 for REALTIME_PRIORITY_CLASS processes.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Every thread has a base priority level determined by the thread's priority value and the priority class of its process. The system uses the base priority level of all executable threads to determine which thread gets the next slice of CPU time. Threads are scheduled in a round-robin fashion at each priority level, and only when there are no executable threads at a higher level does scheduling of threads at a lower level take place.

The SetThreadPriority function enables setting the base priority level of a thread relative to the priority class of its process. For example, specifying THREAD_PRIORITY_HIGHEST in a call to SetThreadPriority for a thread of an IDLE_PRIORITY_CLASS process sets the thread's base priority level to 6. For a table that shows the base priority levels for each combination of priority class and thread priority value, see the SetPriorityClass function.

For IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, and HIGH_PRIORITY_CLASS processes, the system dynamically boosts a thread's base priority level when events occur that are important to the thread. REALTIME_PRIORITY_CLASS processes do not receive dynamic boosts.

All threads initially start at THREAD_PRIORITY_NORMAL. Use the GetPriorityClass and SetPriorityClass functions to get and set the priority class of a process. Use the GetThreadPriority function to get the priority value of a thread.

Use the priority class of a process to differentiate between applications that are time critical and those that have normal or below normal scheduling requirements. Use thread priority values to differentiate the relative priorities of the tasks of a process. For example, a thread that handles input for a window could have a higher priority level than a thread that performs intensive calculations for the CPU.

When manipulating priorities, be very careful  to ensure that a high-priority thread does not consume all of the available CPU time. A thread with a base priority level above 11 interferes with the normal operation of the operating system. Using REALTIME_PRIORITY_CLASS may cause disk caches to not flush, hang the mouse, and so on.

See Also

GetPriorityClass, GetThreadPriority, SetPriorityClass


SetThreadToken
SetThreadToken  (preliminary−Windows NT)

The SetThreadToken function assigns an impersonation token to a thread. The function can also cause a thread to stop using an impersonation token.

BOOL SetThreadToken(

PHANDLE  Thread,	// points to a handle to the thread
HANDLE  Token	// handle to the impersonation token
);
Parameters

Thread

Points to a handle to the thread to which the function assigns the impersonation token.

If Thread is NULL, the function assigns the impersonation token to the calling thread.

Token

An open handle to the impersonation token to assign to the thread.

This handle must have been opened with TOKEN_IMPERSONATE access rights.

If Token is NULL, the function causes the thread to stop using an impersonation token.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

OpenThreadToken


SetTimer

The SetTimer function creates a timer with the specified time-out value.

UINT SetTimer(

HWND  hwnd,	// handle of window for timer messages
UINT  idTimer,	// timer identifier
UINT  uTimeout,	// time-out value
TIMERPROC  tmprc	// address of timer procedure
);
Parameters

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 about the function, see 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.

Return Value

If the function succeeds, the return value is an integer identifying the new timer. An application can pass this value, or the string identifier, if it exists, to the KillTimer function to destroy the timer. If the function fails to create a timer, the return value is zero.

Remarks

An application can process WM_TIMER messages by including a WM_TIMER case statement in the window procedure or by specifying a TimerProc callback function when creating the timer.

The wParam parameter of the WM_TIMER message contains the value of the idTimer parameter.

See Also

KillTimer, MSG, TimerProc, WM_TIMER


SetTimeZoneInformation

The SetTimeZoneInformation function sets the current time-zone parameters. These parameters control translations from Coordinated Universal Time (UTC) to local time.

BOOL SetTimeZoneInformation(

CONST TIME_ZONE_INFORMATION *  lptzi	// address of time-zone settings
);
Parameters

lptzi

Points to a TIME_ZONE_INFORMATION structure that contains the time-zone parameters to set.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

All translations between UTC and local time are based on the following formula:

UTC = local time + bias

The bias is the difference, in minutes, between UTC and local time.

See Also

GetTimeZoneInformation, TIME_ZONE_INFORMATION


SetTokenInformation

The SetTokenInformation function sets various types of information for a specified access token. The information it sets replaces existing information. The calling process must have appropriate access rights to set the information.

BOOL SetTokenInformation(

HANDLE  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
);
Parameters

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, following.

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.
The formats for the structures this function can set are listed in the following Remarks section.

cbInformation

Specifies the length, in bytes, of the buffer pointed to by lpvInformation.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

To set privilege information, an application can call the AdjustTokenPrivileges function. To set a token's groups, an application can call the AdjustTokenGroups function.

Token-type information can be set only when an access token is created.

See Also

AdjustTokenGroups, AdjustTokenPrivileges, GetTokenInformation, OpenProcessToken, OpenThreadToken, TOKEN_DEFAULT_DACL, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP


SetUnhandledExceptionFilter

The SetUnhandledExceptionFilter function lets an application supersede the top-level exception handler that Win32 places at the top of each thread and process.

After calling this function, if an exception occurs in a process that is not being debugged, and the exception makes it to the Win32 unhandled exception filter, that filter will call the exception filter function specified by the lpTopLevelExceptionFilter parameter.

LPTOP_LEVEL_EXCEPTION_FILTER SetUnhandledExceptionFilter(

LPTOP_LEVEL_EXCEPTION_FILTER  lpTopLevelExceptionFilter	// exception filter function
);
Parameters

lpTopLevelExceptionFilter

Supplies the address of a top-level exception filter function that will be called whenever the UnhandledExceptionFilter function gets control, and the process is not being debugged. A value of NULL for this parameter specifies default handling within UnhandledExceptionFilter.

The filter function has syntax congruent to that of UnhandledExceptionFilter: It takes a single parameter of type LPEXCEPTION_POINTERS, and returns a value of type LONG. The filter function should return one of the following values:

Value	Meaning
EXCEPTION_EXECUTE_HANDLER	Return from UnhandledExceptionFilter and execute the associated exception handler. This usually results in process termination.
EXCEPTION_CONTINUE_EXECUTION	Return from UnhandledExceptionFilter and continue execution from the point of the exception. Note that the filter function is free to modify the continuation state by modifying the exception information supplied through its LPEXCEPTION_POINTERS parameter.
EXCEPTION_CONTINUE_SEARCH	Proceed with normal execution of UnhandledExceptionFilter . That means obeying the SetErrorMod flags, or invoking the Application Error pop-up message box.
Return Value

The SetUnhandledExceptionFilter function returns the address of the previous exception filter established with the function. A NULL return value means that there is no current top-level exception handler.

Remarks

Issuing SetUnhandledExceptionFilter replaces the existing top-level exception filter for all existing and all future threads in the calling process.

The exception handler specified by lpTopLevelExceptionFilter is executed in the context of the thread that caused the fault. This can affect the exception handler's ability to recover from certain exceptions, such as an invalid stack.

See Also

UnhandledExceptionFilter


SetupComm

The SetupComm function initializes the communications parameters for a specified communications device.

BOOL SetupComm(

HANDLE  hCommDev,	// handle of communications device
DWORD  cbInQueue,	// size of input buffer
DWORD  cbOutQueue	// size of output buffer
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

After a process uses the CreateFile function to open a handle to a communications device, it can call SetupComm to set the communications parameters for the device. If it does not set them, the device uses the default parameters when the first call to another communications function occurs.

The 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 and output (I/O) buffering scheme, as long as it provides reasonable performance and data is not lost due to overrun (except under extreme circumstances). For example, the function can succeed even though the driver does not allocate a buffer, as long as some other portion of the operating system provides equivalent functionality.

If the device driver determines that the recommended buffer sizes involve transfers beyond its ability to handle, the function can fail.

See Also

CreateFile, SetCommState


SetUserObjectInformation  (preliminaryWindows NT)
SetUserObjectInformation  (preliminary−Windows NT)

The SetUserObjectInformation function sets information about a window station or desktop object.

BOOL SetUserObjectInformation(

HANDLE hObject	// handle of the object for which to set information
int nIndex	// type of information to set
PVOID lpvInfo	// points to a buffer that contains the information
DWORD cbInfo	// size, in bytes, of lpvInfo buffer
);
Parameters

hObject

Identifies the window station or desktop object for which to set object information. This value can be an HDESK or HWINSTA handle (for example, a handle returned by CreateWindowStation, OpenWindowStation, CreateDesktop, or OpenDesktop).

nIndex

Specifies the object information to be set. This parameter must specify the following value:

Value	Description
UOI_FLAGS	Sets the object's handle flags. The lpvInfo parameter must point to a USEROBJECTFLAGS structure.
lpvInfo

Points to a buffer containing the object information.

cbInfo

Specifies the size, in bytes, of the information contained in the buffer pointed to by lpvInfo.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateDesktop, CreateWindowStation, GetUserObjectInformation, OpenDesktop,.OpenWindowStation, USEROBJECTFLAGS


SetUserObjectSecurity

The SetUserObjectSecurity function sets the security of a user object. This can be, for example, a window or a DDE conversation.

BOOL SetUserObjectSecurity(

HANDLE  hObject,	// handle of user object
PSECURITY_INFORMATION  psi,	// address of security information
PSECURITY_DESCRIPTOR  psd	// address of security descriptor
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The SetUserObjectSecurity function applies changes specified in a security descriptor to the security descriptor assigned to a user object. The object's security descriptor must be in self-relative form. If necessary, this function allocates additional memory to increase the size of the security descriptor.

The SetUserObjectSecurity function is successful only if the following conditions are met:

•	If the object's owner is being set, the calling process must either have WRITE_OWNER permission or be the object's owner.

•	If the object's discretionary access-control list (ACL) is being set, the calling process must either have WRITE_DAC permission or be the object's owner.

•	If the object's system ACL is being set, the SE_SECURITY_NAME privilege must be enabled for the calling process.

See Also

GetUserObjectSecurity, SECURITY_DESCRIPTOR, SECURITY_INFORMATION, SetFileSecurity, SetKernelObjectSecurity, SetPrivateObjectSecurity


SetViewportExt

The SetViewportExt function is not implemented in the Win32 API. Win32-based applications should use the SetViewportExtEx function.


SetViewportExtEx

The SetViewportExtEx function sets the horizontal and vertical extents of the viewport for a device context by using the specified values.

BOOL SetViewportExtEx(

HDC  hdc,	// handle of device context
int  nXExtent,	// new horizontal viewport extent
int  nYExtent,	// new vertical viewport extent
LPSIZE  lpSize	// original viewport extent
);
Parameters

hdc

Identifies the device context.

nXExtent

Specifies the horizontal extent, in device units, of the viewport.

nYExtent

Specifies the vertical extent, in device units, of the viewport.

lpSize

Points to a SIZE structure. The previous viewport extents (in device units) are placed in this structure. If lpSize is NULL, nothing is returned.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

When the following mapping modes are set, calls to the SetWindowExtEx and SetViewportExtEx functions are ignored.

•	MM_HIENGLISH

•	MM_HIMETRIC

•	MM_LOENGLISH

•	MM_LOMETRIC

•	MM_TEXT

•	MM_TWIPS

When MM_ISOTROPIC mode is set, an application must call the SetWindowExtEx function before it calls SetViewportExtEx.

See Also

GetViewportExtEx, SetWindowExtEx, SIZE,


SetViewportOrg

The SetViewportOrg function is not implemented in the Win32 API. Win32-based applications should use the SetViewportOrgEx function.


SetViewportOrgEx

The SetViewportOrgEx function sets the viewport origin of a device context by using the specified coordinates.

BOOL SetViewportOrgEx(

HDC  hdc,	// handle of device context
int  X,	// new x-coordinate of viewport origin
int  Y,	// new y-coordinate of viewport origin
LPPOINT  lpPoint	// address of structure receiving original origin
);
Parameters

hdc

Identifies the device context.

X

Specifies the x-coordinate, in device units, of the new viewport origin.

Y

Specifies the y-coordinate, in device units, of the new viewport origin.

lpPoint

Points to a POINT structure. The previous viewport origin (in device coordinates) is placed in this structure. If lpPoint is NULL, nothing is returned.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

GetViewportOrgEx, POINT, SetWindowOrgEx


SetVoiceAccent

The SetVoiceAccent function is not implemented in the Win32 API.

See Also

Beep, MessageBeep


SetVoiceEnvelope

The SetVoiceEnvelope function is not implemented in the Win32 API.

See Also

Beep, MessageBeep


SetVoiceNote

The SetVoiceNote function is not implemented in the Win32 API.

See Also

Beep, MessageBeep


SetVoiceQueueSize

The SetVoiceQueueSize function is not implemented in the Win32 API.

See Also

Beep, MessageBeep


SetVoiceSound

The SetVoiceSound function is not implemented in the Win32 API.

See Also

Beep, MessageBeep


SetVoiceThreshold

The SetVoiceThreshold function is not implemented in the Win32 API.

See Also

Beep, MessageBeep


SetVolumeLabel

The SetVolumeLabel function sets the label of a file system volume.

BOOL SetVolumeLabel(

LPCTSTR  lpRootPathName,	// address of name of root directory for volume
LPCTSTR  lpVolumeName	// name for the volume
);
Parameters

lpRootPathName

Points to a null-terminated string specifying the root directory of a file system volume. This is the volume the function will label. If this parameter is NULL, the root of the current directory is used.

lpVolumeName

Points to a string specifying a name for the volume. If this parameter is NULL, the function deletes the name of the specified volume.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetVolumeInformation


SetWindowContextHelpId  (preliminaryWindows NT)
SetWindowContextHelpId  (preliminary−Windows NT)

The SetWindowContextHelpId function associates a help context identifier with the specified window.

BOOL SetWindowContextHelpId(

HWND  hwnd,
DWORD  dwContextHelpId
);
Parameters

hwnd

Handle to the window with which to associate the help context identifier.

dwContextHelpId

Help context identifier.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

If a child window does not have a help context identifier, it inherits the identifier of its parent window. Likewise, if an owned window does not have a help context identifier, it inherits the identifier of its owner window. This inheritance of help context identifiers allows an application to set just one identifier for a dialog box and all of its controls.


SetWindowExt

The SetWindowExt function is not implemented in the Win32 API. Win32-based applications should use the SetWindowExtEx function.


SetWindowExtEx

The SetWindowExtEx function sets the horizontal and vertical extents of the window for a device context by using the specified values.

BOOL SetWindowExtEx(

HDC  hdc,	// handle of device context
int  nXExtent,	// new horizontal window extent
int  nYExtent,	// new vertical window extent
LPSIZE  lpSize	// original window extent
);
Parameters

hdc

Identifies the device context.

nXExtent

Specifies the window's horizontal extent in logical units.

nYExtent

Specifies the window's vertical extent in logical units.

lpSize

Points to a SIZE structure. The previous window extents (in logical units) are placed in this structure. If lpSize is NULL, nothing is returned.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

When the following mapping modes are set, calls to the SetWindowExtEx and SetViewportExtEx functions are ignored:

•	MM_HIENGLISH

•	MM_HIMETRIC

•	MM_LOENGLISH

•	MM_LOMETRIC

•	MM_TEXT

•	MM_TWIPS

When MM_ISOTROPIC mode is set, an application must call the SetWindowExtEx function before calling SetViewportExtEx.

See Also

GetWindowExtEx, SetViewportExtEx, SIZE


SetWindowLong

The SetWindowLong function changes an attribute of the specified window. The function also sets a 32-bit (long) value at the specified offset into the extra window memory of a window.

LONG SetWindowLong(

HWND  hwnd,	// handle of window
int  nIndex,	// offset of value to set
LONG  lNewLong	// new value
);
Parameters

hwnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based offset to the value to be set. Valid values are in the range zero through the number of bytes of extra window memory, minus 4; for example, if you specified 12 or more bytes of extra memory, a value of 8 would be an index to the third 32-bit integer. To set any other value, specify one of the following values:

Value	Action
GWL_EXSTYLE	Sets a new extended window style.
GWL_STYLE	Sets a new window style.
GWL_WNDPROC	Sets a new address for the window procedure.
GWL_HINSTANCE	Sets a new application instance handle.
GWL_ID	Sets a new identifier of the window.
GWL_USERDATA	Sets the 32-bit value associated with the window. Each window has a corresponding 32-bit value intended for use by the application that created the window.
The following values are also available when the hwnd parameter identifies a dialog box:

Value	Action
DWL_DLGPROC	Sets the new address of the dialog box procedure.
DWL_MSGRESULT	Sets the return value of a message processed in the dialog box procedure.
DWL_USER	Sets new extra information that is private to the application, such as handles or pointers.
lNewLong

Specifies the replacement value.

Return Value

If the function succeeds, the return value is the previous value of the specified 32-bit integer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The SetWindowLong function fails if the window specified by the hwnd parameter does not belong to the same process as the calling thread.

If you use the SetWindowLong function and the GWL_WNDPROC index to replace the window procedure, the window procedure must conform to the guidelines specified in the description of the WindowProc callback function.

Calling SetWindowLong with the GWL_WNDPROC index creates a subclass of the window class used to create the window. An application should not subclass a window created by another process. The SetWindowLong function creates the window subclass by changing the window procedure associated with a particular window, causing Windows to call the new window procedure instead of the previous one. An application must pass any messages not processed by the new window procedure to the previous window procedure by calling CallWindowProc. This allows the application to create a chain of window procedures.

Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the WNDCLASS structure used with the RegisterClass function.

You must not call SetWindowLong with the GWL_HWNDPARENT index to change the parent of a child window. Instead, use the SetParent function.

See Also

CallWindowProc, GetWindowLong, GetWindowWord, RegisterClass, SetParent, SetWindowWord, WindowProc, WNDCLASS


SetWindowOrg

The SetWindowOrg function is not implemented in the Win32 API. Win32-based applications should use the SetWindowOrgEx function.


SetWindowOrgEx

The SetWindowOrgEx function sets the window origin of the device context by using the specified coordinates.

BOOL SetWindowOrgEx(

HDC  hdc,	// handle of device context
int  X,	// new x-coordinate of window origin
int  Y,	// new y-coordinate of window origin
LPPOINT  lpPoint	// address of structure receiving original origin
);
Parameters

hdc

Identifies the device context.

X

Specifies the logical x-coordinate of the new window origin.

Y

Specifies the logical y-coordinate of the new window origin.

lpPoint

Points to a POINT structure. The previous origin of the window is placed in this structure. If lpPoint is NULL, nothing is returned.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

GetViewportOrgEx, GetWindowOrgEx, POINT, SetViewportOrgEx


SetWindowPlacement

The SetWindowPlacement function sets the show state and the restored, minimized, and maximized positions of the specified window.

BOOL SetWindowPlacement(

HWND  hwnd,	// handle of window
CONST WINDOWPLACEMENT *  lpwndpl	// address of structure with position data
);
Parameters

hwnd

Identifies the window.

lpwndpl

Points to a WINDOWPLACEMENT structure that specifies the new show state and window positions.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetWindowPlacement, WINDOWPLACEMENT


SetWindowPos

The SetWindowPos function changes the size, position, and Z order of a child, pop-up, or top-level window. Child, pop-up, and top-level windows are ordered according to their appearance on the screen. The topmost window receives the highest rank and is the first window in the Z order.

BOOL SetWindowPos(

HWND  hwnd,	// handle of window
HWND  hwndInsertAfter,	// placement-order handle
int  x,	// horizontal position
int  y,	// vertical position
int  cx,	// width
int  cy,	// height
UINT  fuFlags	// window-positioning flags
);
Parameters

hwnd

Identifies the window.

hwndInsertAfter

Identifies the window to precede the positioned window in the Z order. This parameter must be a window handle or one of the following values:

Value	Meaning
HWND_BOTTOM	Places the window at the bottom of the Z order. If the hwnd parameter identifies a topmost window, the window loses its topmost status and is placed at the bottom of all other windows.
HWND_NOTOPMOST	Places the window above all non-topmost windows (that is, behind all topmost windows). This flag has no effect if the window is already a non-topmost window.
HWND_TOP	Places the window at the top of the Z order.
HWND_TOPMOST	Places the window above all non-topmost windows. The window maintains its topmost position even when it is deactivated.
For more information about how this parameter is used, see the following Remarks section.

x

Specifies the new position of the left side of the window.

y

Specifies the new position of the top of the window.

cx

Specifies the new width of the window, in pixels.

cy

Specifies the new height of the window, in pixels.

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 redrawing.
SWP_NOZORDER	Retains the current Z order (ignores the hwndInsertAfter parameter).
SWP_SHOWWINDOW	Displays the window.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the SWP_SHOWWINDOW or SWP_HIDEWINDOW flag is set, the window cannot be moved or sized.

All coordinates for child windows are client coordinates (relative to the upper-left corner of the parent window's client area).

A window can be made a topmost window either by setting the hwndInsertAfter parameter to HWND_TOPMOST and ensuring that the SWP_NOZORDER flag is not set, or by setting a window's position in the Z order so that it is above any existing topmost windows. When a non-topmost window is made topmost, its owned windows are also made topmost. Its owners, however, are not changed.

If neither the SWP_NOACTIVATE nor SWP_NOZORDER flag is specified (that is, when the application requests that a window be simultaneously activated and its position in the Z order changed), the value specified in hwndInsertAfter is used only in the following circumstances:

•	Neither the HWND_TOPMOST nor HWND_NOTOPMOST flag is specified in hwndInsertAfter.

•	The window identified by hwnd is not the active window.

An application cannot activate an inactive window without also bringing it to the top of the Z order. Applications can change an activated window's position in the Z order without restrictions, or it can activate a window and then move it to the top of the topmost or non-topmost windows.

If a topmost window is repositioned to the bottom (HWND_BOTTOM) of the Z order or after any non-topmost window, it is no longer topmost. When a topmost window is made non-topmost, its owners and its owned windows are also made non-topmost windows.

A non-topmost window can own a topmost window, but the reverse cannot occur. Any window (for example, a dialog box) owned by a topmost window is itself made a topmost window, to ensure that all owned windows stay above their owner.

If an application is not in the foreground, and should be in the foreground, it must call the SetForegroundWindow function.

See Also

MoveWindow, SetActiveWindow, SetForegroundWindow


SetWindowRgn  (preliminaryWindows NT)
SetWindowRgn  (preliminary−Windows NT)

The SetWindowRgn function sets the window region of a window. The window region determines the area within the window where the operating system permits drawing. The operating system does not display any portion of a window that lies outside of the window region

int SetWindowRgn(

HWND  hWnd,	// handle to window whose window region is to be set
HRGN  hRgn,	// handle to region
BOOL  bRedraw	// window redraw flag
);
Parameters

hWnd

Handle to the window whose window region is to be set.

hRgn

Handle to a region. The function sets the window region of the window to this region.

If hRgn is NULL, the function sets the window region to NULL.

bRedraw

Boolean value that specifies whether the operating system redraws the window after setting the window region. If bRedraw is TRUE, the operating system does so; otherwise, it does not.

Typically, you set bRedraw to TRUE if the window is visible.

Return Value

If the function succeeds, the return value is non-zero.

If the function fails, the return value is zero.

Comments

If the bRedraw parameter is TRUE, the system sends the WM_WINDOWPOSCHANGING and WM_WINDOWPOSCHANGED messages to the window.

The coordinates of a window's window region are relative to the upper-left corner of the window, not the client area of the window.

After a successful call to SetWindowRgn, the operating system owns the region specified by the region handle hRgn. The operating system does not make a copy of the region. Thus, you should not make any further function calls with this region handle. In particular, do not close this region handle.

To obtain the window region of a window, call the GetWindowRgn function.

See Also

GetWindowRgn, WM_WINDOWPOSCHANGING


SetWindowsHook

The SetWindowsHook function is not implemented in the Win32 API. Win32-based applications should use the SetWindowsHookEx function.


SetWindowsHookEx

The SetWindowsHookEx function installs an application-defined hook procedure into a hook chain. An application installs a hook procedure to monitor the system for certain types of events. A hook procedure can monitor events associated either with a specific thread or with all threads in the system. This function supersedes the SetWindowsHook function.

HHOOK SetWindowsHookEx(

int  idHook,	// type of hook to install
HOOKPROC  hkprc,	// address of hook procedure
HINSTANCE  hMod,	// handle of application instance
DWORD  dwThreadID	// identity of thread to install hook for
);
Parameters

idHook

Specifies the type of hook procedure to be installed. This parameter can be one of the following values:

Value	Description
WH_CALLWNDPROC	Installs a hook procedure that monitors messages before the system sends them to the destination window procedure. For more information,  the CallWndProc hook procedure.
WH_CALLWNDPROCRET	Windows 95 only: Installs a hook procedure that monitors messages after they have been processed by the destination window procedure. For more information, see  the CallWndRetProc hook procedure.
WH_CBT	Installs a hook procedure that receives notifications useful to a computer-based training (CBT) application. For more information, see the CBTProc hook procedure.
WH_DEBUG	Installs a hook procedure useful for debugging other hook procedures. For more information, see the DebugProc hook procedure.
WH_GETMESSAGE	Installs a hook procedure that monitors messages posted to a message queue. For more information, see the GetMsgProc hook procedure.
WH_JOURNALPLAYBACK	Installs a hook procedure that posts messages previously recorded by a WH_JOURNALRECORD hook procedure. For more information, see the JournalPlaybackProc hook procedure.
WH_JOURNALRECORD	Installs a hook procedure that records input messages posted to the system message queue. This hook is useful for recording macros. For more information, see the JournalRecordProc hook procedure.
WH_KEYBOARD	Installs a hook procedure that monitors keystroke messages. For more information, see the KeyboardProc hook procedure.
WH_MOUSE	Installs a hook procedure that monitors mouse messages. For more information, see the MouseProc hook procedure.
WH_MSGFILTER	Installs a hook procedure that monitors messages generated as a result of an input event in a dialog box, message box, menu, or scroll bar. For more information, see  the MessageProc hook procedure.
WH_SHELL	Installs a hook procedure that receives notifications useful to shell applications. For more information, see  the ShellProc hook procedure.
WH_SYSMSGFILTER	Installs a hook procedure that monitors messages generated as a result of an input event in a dialog box, message box, menu, or scroll bar. The hook procedure monitors these messages for all applications in the system. For more information, see  the SysMsgProc hook procedure.
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.

Return Value

If the function succeeds, the return value is the handle of the hook procedure.

If the function fails, the return value is NULL.

Remarks

An error may occur if the hMod parameter is NULL and the dwThreadId parameter is zero or specifies the identifier of a thread created by another process.

Chaining to the next hook procedure (that is, calling the CallNextHookEx function) is optional. An application or library can call the next hook procedure either before or after any processing in its own hook procedure.

Before terminating, an application must call the UnhookWindowsHookEx function to free system resources associated with the hook.

The scope of a hook depends on the hook type. Some hooks can be set only with system scope; others can also be set for only a specific thread, as shown in the following list:

Hook	Scope
WH_CALLWNDPROC	Thread or system
WH_CBT	Thread or system
WH_DEBUG	Thread or system
WH_GETMESSAGE	Thread or system
WH_JOURNALPLAYBACK	System only
WH_JOURNALRECORD	System only
WH_KEYBOARD	Thread or system
WH_MOUSE	Thread or system
WH_MSGFILTER	Thread or system
WH_SHELL	Thread or system
WH_SYSMSGFILTER	System only
For a specified hook type, thread hooks are called first, then system hooks.

The system hooks are a shared resource, and installing one affects all applications. All system hook functions must be in libraries. System hooks should be restricted to special-purpose applications or to use as a development aid during application debugging. Libraries that no longer need a hook should remove the hook procedure.

See Also

CallNextHookEx, CallWndProc, CBTProc, DebugProc, GetMsgProc, JournalPlaybackProc, JournalRecordProc, KeyboardProc, MouseProc, MessageProc, ShellProc, SysMsgProc, UnhookWindowsHookEx


SetWindowText

The SetWindowText function changes the text of the specified window's title bar (if it has one). If the specified window is a control, the text of the control is changed.

BOOL SetWindowText(

HWND  hwnd,	// handle of window or control
LPCTSTR  lpsz	// address of string
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The SetWindowText function causes a WM_SETTEXT message to be sent to the specified window or control. If the window is a list box control created with the WS_CAPTION style, however, SetWindowText sets the text for the control, not for the list box entries.

The SetWindowText function does not expand tab characters (ASCII code 0x09). Tab characters are displayed as vertical bar (|) characters.

See Also

GetWindowText, WM_SETTEXT


SetWindowWord

The SetWindowWord function replaces the 16-bit (word) value at the specified offset into the extra window memory for the specified window.

WORD SetWindowWord(

HWND  hwnd,	// handle of window
int  nIndex,	// offset of value to set
WORD  wNewWord	// new value
);
Parameters

hwnd

Identifies the window and, indirectly, the class to which the window belongs.

nIndex

Specifies the zero-based byte offset of the value to be replaced. Valid values are in the range zero through the number of bytes of window memory, minus two; for example, if you specified 10 or more bytes of extra window memory, a value of 8 would be an index to the fifth 16-bit integer.

wNewWord

Specifies the replacement value.

Return Value

If the function succeeds, the return value is the previous value of the specified 16-bit integer.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

Reserve extra window memory by specifying a nonzero value in the cbWndExtra member of the WNDCLASS structure used with the RegisterClass function.

The GWW_ values are obsolete in the Win32 API. You must use the SetWindowLong function to set information about the window.

See Also

GetParent, GetWindowLong, GetWindowWord, RegisterClass, SetParent, SetWindowLong, WNDCLASS


SetWinMetaFileBits

The SetWinMetaFileBits function converts a metafile from the older Windows format to the new enhanced format and stores the new metafile in memory.

HENHMETAFILE SetWinMetaFileBits(

UINT  cbBuffer,	// size of buffer
CONST BYTE *  lpbBuffer,	// address of buffered metafile data
HDC  hdcRef,	// handle of reference device context
CONST METAFILEPICT *  lpmfp	// suggested size of metafile picture
);
Parameters

cbBuffer

Specifies the size, in bytes, of the buffer that contains the Windows-format metafile.

lpbBuffer

Points to a buffer that contains the Windows-format metafile data. (It is assumed that the data was obtained by using the GetMetaFileBitsEx or GetWinMetaFileBits function.)

hdcRef

Identifies a reference device context.

lpmfp

Points to a METAFILEPICT structure that contains the suggested size of the metafile picture and the mapping mode that was used when the picture was created.

Return Value

If the function succeeds, the return value is a handle of a memory-based enhanced metafile.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Windows uses the reference device context's resolution data and the data in the METAFILEPICT structure to scale a picture. If the hdcRef parameter is NULL, Windows uses resolution data for the current output device. If the lpmfp parameter is NULL, Windows uses the MM_ANISOTROPIC mapping mode to scale the picture so that it fits the entire device surface. The hMF field in the METAFILEPICT structure is not used.

When the application no longer needs the enhanced metafile handle, it should delete it by calling the DeleteEnhMetaFile function.

The handle returned by this function can be used with other enhanced-metafile functions.

If the reference device context is not identical to the device in which the metafile was originally created, some GDI functions that use device units may not draw the picture correctly.

See Also

DeleteEnhMetaFile, GetWinMetaFileBits, GetMetaFileBitsEx, METAFILEPICT, PlayEnhMetaFile


SetWorldTransform

The SetWorldTransform function sets a two-dimensional linear transformation between world space and page space for the specified device context. This transformation can be used to scale, rotate, shear, or translate graphics output.

BOOL SetWorldTransform(

HDC  hdc,	// handle of device context
CONST XFORM *  lpXform	// address of transformation data
);
Parameters

hdc

Identifies the device context.

lpXform

Points to an XFORM structure that contains the transformation data.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

For any coordinates (x, y) in world space, the transformed coordinates in page space (x', y') can be determined by the following algorithm:

x' = x * eM11 + y * eM21 + eDx,

y' = x * eM12 + y * eM22 + eDy,

where the transformation matrix is represented by the following:

| eM11 eM12 0 |

| eM21 eM22 0 |

| eDx  eDy  1 |

The mapping mode (defined by the current window and viewport extents origins) serves to define units and scales.

The world transformation is usually used to scale or rotate logical images in a device-independent way.

The default world transformation is the identity matrix with zero offset.

The SetWorldTransform function will fail unless the graphics mode for the given device context has been set to GM_ADVANCED by previously calling the SetGraphicsMode function. Likewise, it will not be possible to reset the graphics mode for the device context to the default GM_COMPATIBLE mode, unless the world transformation has first been reset to the default identity transformation by calling SetWorldTransform or ModifyWorldTransform.

See Also

GetWorldTransform, ModifyWorldTransform, SetGraphicsMode, SetMapMode, SetViewportExtEx, SetViewportOrgEx, SetWindowExtEx, SetWindowOrgEx, XFORM


SHAddToRecentDocs

Adds a document to the shell's list of recently used documents or clears all documents from the list. The user accesses the list through the Start menu of the Windows taskbar.

WINSHELLAPI void WINAPI SHAddToRecentDocs(

UINT  uFlags,
LPCVOID  pv
);
Parameters

uFlags

Flag that indicates the meaning of the pv parameter. This parameter can be one of the following values:

SHARD_PATH	pv is the address of a path string.
SHARD_PIDL	pv is the address of an item identifier list.
pv

Pointer to a buffer that contains the path and filename of the document, or the address of an ITEMIDLIST structure that contains an item identifier list uniquely identifying the document. If this parameter is NULL, the function clears all documents from the list.

Return Value

No return value.


SHAppBarMessage

Sends an appbar message to the system.

WINSHELLAPI UINT APIENTRY SHAppBarMessage(

DWORD  dwMessage,
PAPPBARDATA  pabd
);
Parameters

dwMessage

Identifier of the appbar message to send. This parameter can be one of the following values:

ABM_ACTIVATE	Notifies the system that an appbar has been activated.
ABM_GETAUTOHIDEBAR	Retrieves the handle of the autohide appbar associated with a particular edge of the screen.
ABM_GETSTATE	Retrieves the autohide and always-on-top states of the Windows taskbar.
ABM_GETTASKBARPOS	Retrieves the bounding rectangle of the Windows taskbar.
ABM_NEW	Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar.
ABM_QUERYPOS	Requests a size and screen position for an appbar.
ABM_REMOVE	Unregisters an appbar, removing bar from the system's internal list.
ABM_SETAUTOHIDEBAR	Registers or unregisters an autohide appbar for an edge of the screen.
ABM_SETPOS	Sets the size and screen position of an appbar.
ABM_WINDOWPOSCHANGED	Notifies the system when an appbar's position has changed.
pabd

Pointer to an APPBARDATA structure. The content of the structure depends on the value of dwMessage.

Return Value

Returns a message-dependent value. For more information, see the documentation for the individual appbar messages.

See Also

APPBARDATA


SHBrowseForFolder

Displays a dialog box that enables the user to select a shell folder.

WINSHELLAPI LPITEMIDLIST WINAPI SHBrowseForFolder(

LPBROWSEINFO  lpbi
);
Parameter

lpbi

Pointer to a BROWSEINFO structure that contains information used to display the dialog box.

Return Value

Returns a pointer to an item identifier list that specifies the location of the selected folder relative to the root of the name space. If the user chooses the Cancel button in the dialog box, the return value is NULL.

The calling application is responsible for freeing the returned item identifier list using the shell's task allocator.

See Also

BROWSEINFO


SHChangeNotify

Notifies the system of an event that an application has performed. An application should use this function if it performs an action that may affect the shell.

WINSHELLAPI void WINAPI SHChangeNotify(

LONG  wEventId,
UINT  uFlags,
LPCVOID  dwItem1,
LPCVOID  dwItem2
);
Parameters

wEventId

Array of flags that specifies the events. This parameter can be a combination of the following values:

SHCNE_ASSOCCHANGED	Changed a file type association.
SHCNE_ATTRIBUTES	Changed a file's attributes.
SHCNE_CREATE	Created a file.
SHCNE_DELETE	Deleted a file.
SHCNE_DRIVEADD	Added a network drive.
SHCNE_DRIVEADDGUI	Added a network drive by way of a graphic user interface.
SHCNE_DRIVEREMOVED	Removed a network drive.
SHCNE_INTERRUPT	Performed the event as a result of a system interrupt.
SHCNE_MEDIAINSERTED	Added removable media, such as a CD-ROM.
SHCNE_MEDIAREMOVED	Removed a removable medium, such as a CD-ROM.
SHCNE_MKDIR	Created a new directory.
SHCNE_NETSHARE	Shared a resource on the network.
SHCNE_NETUNSHARE	Stopped sharing a resource.
SHCNE_RENAMEFOLDER	Renamed a folder.
SHCNE_RENAMEITEM	Renamed an item in a folder.
SHCNE_RMDIR	Removed a directory.
SHCNE_SERVERDISCONNECT	Disconnected a network server.
SHCNE_UPDATEDIR	Updated the contents of a directory.
SHCNE_UPDATEIMAGE	Changed an image in the system global image list.
SHCNE_UPDATEITEM	Changed the properties of a printer or file.
uFlags

Flag that indicates the meaning of dwItem1 and dwItem2. This parameter can be one of the following values:

SHCNF_DWORD	The dwItem1 and dwItem2 parameters are doubleword values.
SHCNF_FLUSH	Flushes the system event buffer. The function does not return until the system is finished processing the given event.
SHCNF_FLUSHNOWAIT	Flushes the system event buffer. The function returns immediately regardless of whether the system is finished processing the given event.
SHCNF_IDLIST	dwItem1 and dwItem2 are the addresses of item identifier lists.
SHCNF_PATH	dwItem1 and dwItem2 are path names.
SHCNF_PRINTER	dwItem1 and dwItem2 are printer "friendly" names.
dwItem1

First event-dependent value.

dwItem2

Second event-dependent value.

Return Value

No return value.


ShellAbout

The ShellAbout function displays a Shell About dialog box.

int ShellAbout (

HWND  hWnd,	// handle of parent window
LPCTSTR  szApp,	// title bar and first line text
LPCTSTR  szOtherStuff,	// other dialog text
HICON  hIcon	// icon to display
);
Parameters

hWnd

Identifies a parent window. This parameter can be NULL.

szApp

Points to text that the function displays in the title bar of the Shell About dialog box and on the first line of the dialog box after the text "Microsoft Windows" or "Microsoft Windows NT." If the text contains a "#" separator, dividing it into two parts, the function displays the first part in the title bar, and the second part on the first line after the text "Microsoft Windows" or "Microsoft Windows NT."

szOtherStuff

Points to text that the function displays in the dialog box after the version and copyright information.

hIcon

Identifies an icon that the function displays in the dialog box. If this parameter is NULL, the function displays the Microsoft Windows or Microsoft Windows NT icon.

Return Value

If the function succeeds in displaying the dialog box, the return value is TRUE; otherwise the return value is FALSE.

Remarks

Please note that the ShellAbout function dialog box uses text and a default icon that are specific to either Microsoft Windows or Microsoft Windows NT.

An example of a Shell About dialog box can be seen by selecting the About Program Manager command in Program Manager.


ShellExecute

The ShellExecute function opens or prints a specified file. The file can be an executable file or a document file.

HINSTANCE ShellExecute(

HWND  hwnd,	// handle to parent window
LPCTSTR  lpOperation,	// pointer to string that specifies operation to perform
LPCTSTR  lpFile,	// pointer to filename string
LPTSTR  lpParameters,	// pointer to string that specifies executable-file parameters
LPCTSTR  lpDirectory,	// pointer to string that specifies default directory
INT  nShowCmd	// whether file is shown when opened
);
Parameters

hwnd

Specifies a parent window. This window receives any message boxes that an application produces. For example, an application may report an error by producing a message box.

lpOperation

Pointer to a null-terminated string that specifies the operation to perform. The following operation strings are valid:

String	Meaning
"open"	The function opens the file specified by lpFile. The file can be an executable file or a document file.
"print"	The function prints the file specified by lpFile. The file should be a document file. If the file is an executable file, the function opens the file, as if "open" had been specified.
The lpOperation parameter can be NULL. In that case, the function opens the file specified by lpFile.

lpFile

Pointer to a null-terminated string that specifies the file to open or print. The function can open an executable file or a document file. The function can print a document file.

lpParameters

If lpFile specifies an executable file, lpParameters is a pointer to a null-terminated string that specifies parameters to be passed to the application.

If lpFile specifies a document file, lpParameters should be NULL.

lpDirectory

Pointer to a null-terminated string that specifies the default directory.

nShowCmd

If lpFile specifies an executable file, nShowCmd specifies how the application is to be shown when it is opened.

If lpFile specifies a document file, nShowCmd should be  zero.

Return Value

If the function succeeds, the return value is the instance handle of the application that was run, or the handle of a dynamic data exchange [DDE] server application.

If the function fails, the return value is an error value that is less than or equal to 32. The Remarks section that follows lists these error values.

Remarks

The file specified by the lpFile parameter can be a document file or an executable file. If the file is a document file, the ShellExecute function opens or prints it, depending on the value of the lpOperation parameter. If the file is an executable file, the ShellExecute function opens it, even if lpOperation specifies printing.

If the function fails, it returns 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).
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.
See Also

FindExecutable


ShellProc

The ShellProc hook procedure is an application-defined or library-defined callback function a shell application uses to receive useful notifications from the system.

LRESULT CALLBACK ShellProc(

int  nCode,	// hook code
WPARAM  wParam,	// event-specific information
LPARAM  lParam	// undefined
);
Parameters

nCode

Specifies the hook code. This parameter can be one of the following values:

Value	Meaning
HSHELL_ACTIVATESHELLWINDOW	The shell should activate its main window.
HSHELL_GETMINRECT	Windows 95 only: A window is being minimized or maximized and the system needs the coordinates of the minimized rectangle for the window. The wParam parameter contains the handle of the window, and the lParam parameter contains the address of a RECT structure that receives the coordinates.
HSHELL_LANGUAGE	Windows 95 only: Keyboard language was changed or a new keyboard layout was loaded.
HSHELL_REDRAW	Windows 95 only: The title of a window in the task bar has been redrawn. The wParam parameter contains the handle of the window.
HSHELL_TASKMAN	Windows 95 only: The user has selected the task list. The wParam parameter contains the handle of the window. A shell application that provides a task list should return TRUE to prevent Windows from starting its task list.
HSHELL_WINDOWACTIVATED	Windows 95 only: The activation has changed to a different top-level, unowned window. The wParam parameter contains the handle of the window.
HSHELL_WINDOWCREATED	A top-level, unowned window has been created. The window exists when the system calls a ShellProc function.
HSHELL_WINDOWDESTROYED	A top-level, unowned window is about to be destroyed. The window still exists when the system calls a ShellProc function.
If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies additional information the shell application may require. If the nCode parameter is HSHELL_ACTIVATESHELLWINDOW, the wParam parameter is not used. If nCode is HSHELL_WINDOWCREATED or HSHELL_WINDOWDESTROYED, wParam specifies the handle of the window being created or destroyed, respectively.

lParam

Windows 95:

Specifies additional information. The exact value depends on the value of the nCode parameter. If nCode is HSHELL_GETMINRECT, lParam is LPRECT. If nCode is HSHELL_WINDOWSACTIVATED, lParam is fFullScreen. If nCode is HSHELL_REDRAW, lParam is fNewFlash.

Windows NT:

This parameter must be zero.

Return Value

The return value should be zero.

Remarks

An application installs the hook procedure by specifying the WH_SHELL hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

ShellProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, SendMessage, SetWindowsHookEx


SHFileOperation

Performs a copy, move, rename, or delete operation on a file system object.

WINSHELLAPI int WINAPI SHFileOperation(

LPSHFILEOPSTRUCT  lpFileOp
);
Parameter

lpFileOp

Pointer to an SHFILEOPSTRUCT structure that contains information the function needs to carry out the operation.

Return Value

Returns zero if successful or nonzero if an error occurs.

See Also

SHFILEOPSTRUCT


SHFreeNameMappings

Frees a filename mapping object that was retrieved by the SHFileOperation function.

WINSHELLAPI void WINAPI SHFreeNameMappings(;

HANDLE  hNameMappings
);
Parameter

hNameMappings

Handle of the filename mapping object to free.

Return Value

No return value.


SHGetDesktopFolder

Retrieves the IShellFolder interface for the desktop folder, which is the root of the shell's name space.

WINSHELLAPI HRESULT WINAPI SHGetDesktopFolder(

LPSHELLFOLDER * ppshf
);
Parameter

ppshf

Address that receives an IShellFolder interface pointer for the desktop folder. The calling application is responsible for eventually freeing the interface by calling its Release method.

Return Value

Returns NOERROR if successful or an OLE-defined error result otherwise.

See Also

IShellFolder


SHGetFileInfo

Retrieves information about an object in the file system, such as a file, a folder, a directory, or a drive root.

WINSHELLAPI DWORD WINAPI SHGetFileInfo(

LPCSTR  pszPath,
DWORD  dwFileAttributes,
SHFILEINFO FAR  *psfi,
UINT  cbFileInfo,
UINT  uFlags
);
Parameters

pszPath

Pointer to a buffer that contains the path and filename. Both absolute and relative paths are valid. If uFlags includes the SHGFI_PIDL, value pszPath must be the address of an ITEMIDLIST structure that contains the list of item identifiers that uniquely identifies the file within the shell's name space.

dwFileAttributes

Array of file attribute flags (FILE_ATTRIBUTE_ values). If uFlags does not include the SHGFI_USEFILEATTRIBUTES value, this parameter is ignored.

psfi and cbFileInfo

Address and size, in bytes, of the SHFILEINFO structure that receives the file information.

uFlags

Flag that specifies the file information to retrieve. This parameter can be a combination of the following values:

SHGFI_ATTRIBUTES	Retrieves the file attribute flags. The flags are copied to the dwAttributes member of the structure specified by psfi.
SHGFI_DISPLAYNAME	Retrieves the display name for the file. The name is copied to the szDisplayName member of the structure specified by psfi.
SHGFI_EXETYPE	Returns the type of the executable file if pszPath identifies an executable file. For more information, see the comments below.
SHGFI_ICON	Retrieves the handle of the icon that represents the file and the index of the icon within the system image list. The handle is copied to the hIcon member of the structure specified by psfi, and the index is copied to the iIcon member. The return value is the handle of the system image list.
SHGFI_ICONLOCATION	Retrieves the name of the file that contains the icon representing the file. The name is copied to the szDisplayName member of the structure specified by psfi.
SHGFI_LARGEICON	Modifies SHGFI_ICON, causing the function to retrieve the file's large icon.
SHGFI_LINKOVERLAY	Modifies SHGFI_ICON, causing the function to add the link overlay to the file's icon.
SHGFI_OPENICON	Modifies SHGFI_ICON, causing the function to retrieve the file's open icon. A container object displays an open icon to indicate that the container is open.
SHGFI_PIDL	Indicates that pszPath is the address of an ITEMIDLIST structure rather than a path name.
SHGFI_SELECTED	Modifies SHGFI_ICON, causing the function to blend the file's icon with the system highlight color.
SHGFI_SHELLICONSIZE	Modifies SHGFI_ICON, causing the function to retrieve a shell-sized icon. If this flag is not specified, the function sizes the icon according to the system metric values.
SHGFI_SMALLICON	Modifies SHGFI_ICON, causing the function to retrieve the file's small icon.
SHGFI_SYSICONINDEX	Retrieves the index of the icon within the system image list. The index is copied to the iIcon member of the structure specified by psfi. The return value is the handle of the system image list.
SHGFI_TYPENAME	Retrieves the string that describes the file's type. The string is copied to the szTypeName member of the structure specified by psfi.
SHGFI_USEFILEATTRIBUTES	Indicates that the function should use the dwFileAttributes parameter.
To retrieve the executable file type, uFlags must specify only SHGFI_EXETYPE. The return value specifies the type of the executable file:

0	Nonexecutable file or an error condition.
LOWORD = NE or PE HIWORD = 3.0, 3.5, or 4.0	Windows application
LOWORD = MZ HIWORD = 0	MS-DOS .EXE, .COM or .BAT file
LOWORD = PE HIWORD = 0	Win32 console application
Return Value

•	Returns a value whose meaning depends on the uFlags parameter. If uFlags specifies the SHGFI_EXETYPE value, the return value indicates the type of the executable file. For more information, see the comments below.

•	If uFlags includes the SHGFI_ICON or SHGFI_SYSICONINDEX value, the return value is the handle of the system image list that contains the large icon images. If the SHGFI_SMALLICON value is also included, the return value is the handle of the image list that contains the small icon images.

•	If uFlags does not include SHGFI_EXETYPE, SHGFI_ICON, SHGFI_SYSICONINDEX, or SHGFI_SMALLICON, the return value is nonzero the function succeeds, or zero otherwise.


SHGetInstanceExplorer

Retreives the address of the Explorer's IUnknown interface.

WINSHELLAPI HRESULT WINAPI SHGetInstanceExplorer(

IUnknown  **ppunk
);
Parameter

ppunk

Pointer to a value that receives the address of the Explorer's IUnknown interface.

Return Value

Returns NOERROR if successful or E_FAIL otherwise.


SHGetNameMappingCount

Retrieves the number of SHNAMEMAPPING structures in a filename mapping object.

int SHGetNameMappingCount(

HANDLE  hNameMappings
);
Parameter

hNameMapping

Handle of a filename mapping object retrieved by the SHFileOperation function.

Return Value

Returns the number of SHNAMEMAPPING structures.

The SHGetNameMappingCount macro is defined as follows.

#define SHGetNameMappingCount(_hnm) \
    DSA_GetItemCount(_hnm)

See Also

SHFileOperation, SHNAMEMAPPING


SHGetNameMappingPtr

Retrieves the address of a SHNAMEMAPPING structure contained in a file mapping object.

lpshnm = SHGetNameMappingPtr(

HANDLE  hNameMappings,
int  iItem
);
Parameters

hNameMapping

Handle of a filename mapping object retrieved by the SHFileOperation function.

iItem

Index of the SHNAMEMAPPING structure to be retrieved.

Return Value

Returns the address of the SHNAMEMAPPING structure specified by iItem.

The SHGetNameMappingPtr macro is defined as follows.

#define SHGetNameMappingPtr(_hnm, _iItem) \
    (LPSHNAMEMAPPING)DSA_GetItemPtr(_hnm, _iItem)

See Also

SHFileOperation, SHNAMEMAPPING


SHGetPathFromIDList

Converts an item identifier list to a file system path.

WINSHELLAPI BOOL WINAPI SHGetPathFromIDList(

LPCITEMIDLIST  pidl,
LPSTR  pszPath
);
Parameters

pidl

Pointer to an item identifier list that specifies a file or directory location relative to the root of the name space (the desktop).

pszPath

Pointer to a buffer that receives the file system path. The size of this buffer is assumed to be MAX_PATH bytes.

Return Value

Returns TRUE if successful or FALSE if an error occurs — for example, if the location specified by the pidl parameter is not part of the file system.


SHGetSpecialFolderLocation

WINSHELLAPI HRESULT WINAPI SHGetSpecialFolderLocation(HWND hwndOwner,

    int nFolder, LPITEMIDLIST * ppidl);

Retrieves the location of a special folder.

Parameters

hwndOwner

Handle of the owner window that the client should specify if it displays a dialog box or message box.

nFolder

Value specifying the folder to retrieve the location of. This parameter can be one of the following values:

CSIDL_BITBUCKET	Recycle bin — file system directory containing file objects in the user's recycle bin. The location of this directory is not in the registry; it is marked with the hidden and system attributes to prevent the user from moving or deleting it.
CSIDL_CONTROLS	Control Panel — virtual folder containing icons for the control panel applications.
CSIDL_DESKTOP	Windows desktop — virtual folder at the root of the name space.
CSIDL_DESKTOPDIRECTORY	File system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself).
CSIDL_DRIVES	My Computer — virtual folder containing everything on the local computer: storage devices, printers, and Control Panel. The folder may also contain mapped network drives.
CSIDL_FONTS	Virtual folder containing fonts.
CSIDL_NETHOOD	File system directory containing objects that appear in the network neighborhood.
CSIDL_NETWORK	Network Neighborhood — virtual folder representing the top level of the network hierarchy.
CSIDL_PERSONAL	File system directory that serves as a common respository for documents.
CSIDL_PRINTERS	Printers folder — virtual folder containing installed printers.
CSIDL_PROGRAMS	File system directory that contains the user's program groups (which are also file system directories).
CSIDL_RECENT	File system directory that contains the user's most recently used documents.
CSIDL_SENDTO	File system directory that contains Send To menu items.
CSIDL_STARTMENU	File system directory containing Start menu items.
CSIDL_STARTUP	File system directory that corresponds to the user's Startup program group.
CSIDL_TEMPLATES	File system directory that serves as a common repository for document templates.
ppidl

Address that receives a pointer to an item identifier list specifying the folder's location relative to the root of the name space (the desktop).

Return Value

Returns NOERROR if successful or an OLE-defined error result otherwise.


SHLoadInProc

Creates an instance of the specified object class from within the context of the shell's process.

WINSHELLAPI HRESULT WINAPI SHLoadInProc(

REFCLSID  rclsid
);
Parameter

rclsid

CLSID of the object class to be created.

Return Value

Returns NOERROR if successful or an OLE-defined error result otherwise.


ShowCaret

The ShowCaret function makes the caret visible on the screen at the caret's current position. When the caret becomes visible, it begins flashing automatically.

BOOL ShowCaret(

HWND  hwnd	// handle of window with caret
);
Parameters

hwnd

Identifies the window that owns the caret. If this parameter is NULL, ShowCaret searches the current task for the window that owns the caret.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

ShowCaret shows the caret only if the specified window owns the caret, the caret has a shape, and the caret has not been hidden two or more times in a row. If one or more of these conditions is not met, ShowCaret does nothing and returns FALSE.

Hiding is cumulative. If your application calls HideCaret five times in a row, it must also call ShowCaret five times before the caret reappears.

The caret is a shared resource; there is only one caret in the system. A window should show a caret only when the window has the keyboard focus or is active.

See Also

CreateCaret, DestroyCaret, GetCaretPos, HideCaret, SetCaretPos


ShowCursor

The ShowCursor function displays or hides the cursor.

int ShowCursor(

BOOL  bShow	// cursor visibility flag
);
Parameters

bShow

Specifies whether the internal display counter is to be incremented or decremented. If bShow is TRUE, the display count is incremented by one. If bShow is FALSE, the display count is decremented by one.

Return Value

The return value specifies the new display counter.

Remarks

This function sets an internal display counter that determines whether the cursor should be displayed. The cursor is displayed only if the display count is greater than or equal to 0. If a mouse is installed, the initial display count is 0. If no mouse is installed, the display count is −1.

See Also

ClipCursor, GetCursorPos, SetCursor, SetCursorPos


ShowHideMenuCtl  (preliminaryWindows NT)
ShowHideMenuCtl  (preliminary−Windows NT)

The ShowHideMenuCtl function sets or removes the specified menu item's check-mark attribute, and shows or hides the corresponding control. The function adds a check mark to the specified menu item if it does not have one and then displays the corresponding control. If the menu item already has a check mark, the function removes the check mark and hides the corresponding control.

BOOL ShowHideMenuCtl(

HWND  hWnd,	// handle to MDI child window
UINT  uFlags,	// message
LPINT  lpInfo	// first message parameter
);
Parameters

hWnd

Handle to the window that contains the menu and controls.

uFlags

Identifier of the menu item to receive or lose a check mark.

lpInfo

Pointer to an array that contains pairs of values. The second value in the first pair must be the handle to the application's main menu. Each subsequent pair consists of a menu item identifier and a control window identifier. The function searches the array for a value that matches uFlags and, if the value is found, checks or unchecks the menu item and shows or hides the corresponding control.

Return Value

If the function shows or hides the control, the return value is TRUE.

If the function does not show or hide the control, the return value is FALSE.


ShowOwnedPopups

The ShowOwnedPopups function shows or hides all pop-up windows owned by the specified window.

BOOL ShowOwnedPopups(

HWND  hwnd,	// handle of window
BOOL  fShow	// window visibility flag
);
Parameters

hwnd

Identifies the window that owns the pop-up windows to be shown or hidden.

fShow

Specifies whether pop-up windows are to be shown or hidden. If this parameter is TRUE, all hidden pop-up windows are shown. If this parameter is FALSE, all visible pop-up windows are hidden.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

ShowOwnedPopups shows only windows hidden by a previous call to ShowOwnedPopups. For example, if a pop-up window is hidden by using the ShowWindow function, subsequently calling ShowOwnedPopups with the fShow parameter set to TRUE does not cause the window to be shown.

See Also

IsWindowVisible, ShowWindow


ShowScrollBar

The ShowScrollBar function shows or hides the specified scroll bar.

BOOL ShowScrollBar(

HWND  hwnd,	// handle of window with scroll bar
int  fnBar,	// scroll bar flag
BOOL  fShow	// scroll bar visibility flag
);
Parameters

hwnd

Identifies a scroll bar control or a window with a standard scroll bar, depending on the value of the 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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

While processing a scroll bar message, an application should not call this function to hide a scroll bar.

See Also

GetScrollPos, GetScrollRange, ScrollDC, ScrollWindow, SetScrollPos, SetScrollRange


ShowWindow

The ShowWindow function sets the specified window's show state.

BOOL ShowWindow(

HWND  hwnd,	// handle of window
int  nCmdShow	// show state of window
);
Parameters

hwnd

Identifies the window.

nCmdShow

Specifies how the window is to be shown. This parameter can be one of the following values:

Value	Meaning
SW_HIDE	Hides the window and activates another window.
SW_MAXIMIZE	Maximizes the specififed window.
SW_MINIMIZE	Minimizes the specified window and activates the next top-level window in the Z order.
SW_RESTORE	Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.
SW_SHOW	Activates the window and displays it in its current size and position.
SW_SHOWDEFAULT	Sets the show state based on the SW_ flag specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application. An application should call ShowWindow with this flag to set the initial show state of its main window.
SW_SHOWMAXIMIZED	Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED	Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE	Displays the window as a minimized window. The active window remains active.
SW_SHOWNA	Displays the window in its current state. The active window remains active.
SW_SHOWNOACTIVATE	Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.
Return Value

If the window was previously visible, the return value is TRUE. If the window was previously hidden, the return value is FALSE.

Remarks

ShowWindow must be called only once per program with the WinMain function's nCmdShow parameter. Subsequent calls to ShowWindow must use one of the values in the preceding list, instead of the one specified by the WinMain function's nCmdShow parameter.

As noted in the discussion of the nCmdShow parameter, an application should call ShowWindow with nCmdShow set to SW_SHOWDEFAULT to use application startup information that affects how a window is displayed. For example, Program Manager specifies that applications start with a minimized main window. Win32-based applications also use the application startup information when calling ShowWindow for the first time and set nCmdShow to SW_SHOW. 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

CreateProcess, CreateWindow, ShowOwnedPopups, STARTUPINFO, WinMain


ShowWindowAsync  (preliminaryWindows 95)
ShowWindowAsync  (preliminary−Windows 95)

The ShowWindowAsync function sets the show state of a window created by a different thread.

BOOL ShowWindowAsync(

HWND  hwnd,	// handle of window
int  nCmdShow	// show state of window
);
Parameters

hwnd

Identifies the window.

nCmdShow

Specifies how the window is to be shown. For a list of possible values, see the description of the ShowWindow function.

Return Value

If the window was previously visible, the return value is TRUE.

If the window was previously hidden, the return value is FALSE.

Remarks

This function posts a show-window event to the message queue of the given window. An application can use this function to avoid becoming hung while waiting for a hung application to finish processing a show-window event.

See Also

ShowWindow


shutdown

The Windows Sockets shutdown function disables send or receive operations on a socket.

int shutdown (

SOCKET s,
int how
);
Parameters

s

A descriptor identifying a socket.

how

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

Return Value

If the function succeeds, shutdown returns zero.

If the function fails, a value of SOCKET_ERROR is returned. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINVAL	The how parameter is not valid.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAENOTCONN	The socket is not connected (SOCK_STREAM only).
WSAENOTSOCK	The descriptor is not a socket.
Remarks

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

If how is zero, subsequent receives on the socket will be disallowed. This has no effect on the lower protocol layers. For TCP, the TCP window is not changed, and incoming data will be accepted (but not acknowledged) until the window is exhausted. For UDP, incoming datagrams are accepted and queued. In no case will an ICMP error packet be generated.

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

Setting how to 2 disables both sends and receives as described previously.

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

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

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

See Also

closesocket, connect, socket, WSAStartup


SizeofResource

The SizeofResource function returns the size, in bytes, of the specified resource.

DWORD SizeofResource(

HINSTANCE  hModule,	// resource-module handle
HRSRC  hrsrc	// resource handle
);
Parameters

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.

Return Value

If the function succeeds, the return value is the number of bytes in the resource.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The value returned may be larger than the actual resource because of alignment. An application should not rely upon this value for the exact size of a resource.

See Also

FindResource, FindResourceEx , LoadResource, LockResource


Sleep

The Sleep function suspends the execution of the current thread for a specified interval.

VOID Sleep(

DWORD  cMilliseconds	// sleep time in milliseconds
);
Parameters

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.

Return Value

This function does not return a value.

Remarks

A thread can relinquish the remainder of its time slice by calling this function with a sleep time of zero milliseconds.

See Also

SleepEx


SleepEx

The SleepEx function causes the current thread to enter a wait 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.

DWORD SleepEx(

DWORD  dwTimeout,	// time-out interval in milliseconds
BOOL  fAlertable	// early completion flag
);
Parameters

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 function. 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 function occurs. If an I/O completion callback occurs, the I/O completion function is executed.

Return Value

The return value is zero if the specified time interval expired.

The return value is WAIT_IO_COMPLETION if the function returned due to one or more I/O completion callback functions. This can happen only if fAlertable is TRUE, and if the thread that called the SleepEx function is the same thread that called the extended I/O function.

Remarks

This function can be used with the ReadFileEx or WriteFileEx functions to suspend a thread until an I/O operation has been completed. These functions specify a completion routine that is to be executed when the I/O operation has been completed. For the completion routine to be executed, the thread that called the I/O function must be in an alertable wait state when the completion callback function occurs. A thread goes into an alertable wait state by calling either SleepEx, WaitForSingleObjectEx, or WaitForMultipleObjectsEx with the function's fAlertable parameter set to TRUE.

A thread can relinquish the remainder of its time slice by calling this function with a sleep time of zero milliseconds.

See Also

ReadFileEx, Sleep, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFileEx


socket

TheWindows Sockets socket function creates a socket.

SOCKET socket (

int af,
int type,
int protocol
);
Parameters

af

An address format specification. The only format currently supported is PF_INET, which is the ARPA Internet address format.

type

A type specification for the new socket.

protocol

A particular protocol to be used with the socket, or zero if the caller does not wish to specify a protocol.

Return Value

If the function succeeds, socket returns a descriptor referencing the new socket.

If the function fails, a value of INVALID_SOCKET is returned. To get extended error information, call WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEAFNOSUPPORT	The specified address family is not supported.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEMFILE	No more file descriptors are available.
WSAENOBUFS	No buffer space is available. The socket cannot be created.
WSAEPROTONOSUPPORT	The specified protocol is not supported.
WSAEPROTOTYPE	The specified protocol is the wrong type for this socket.
WSAESOCKTNOSUPPORT	The specified socket type is not supported in this address family.
Remarks

The socket function allocates a socket descriptor of the specified address family, data type and protocol, as well as related resources. If a protocol is not specified (that is, equal to zero), the default for the specified connection mode is used.

Only a single protocol exists to support a particular socket type using a given address format. However, the address family may be given as AF_UNSPEC (unspecified), in which case the protocol parameter must be specified. The protocol number to use is particular to the "communication domain" in which communication is to take place.

The following type specifications are supported:

Value	Meaning
SOCK_STREAM	Provides sequenced, reliable, two-way, connection-based byte streams with an out-of-band data transmission mechanism. Uses TCP for the Internet address family.
SOCK_DGRAM	Supports datagrams, which are connectionless, unreliable buffers of a fixed (typically small) maximum length. Uses UDP for the Internet address family.
Sockets of type SOCK_STREAM are full-duplex byte streams. A stream socket must be in a connected state before any data can be sent or received on it. A connection to another socket is created with a connect call. Once connected, data can be transferred using send and recv calls. When a session has been completed, a closesocket must be performed. Out-of-band data can also be transmitted as described in send and received as described in recv.

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

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

See Also

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


SoundSentryProc  (preliminaryWindows NT)
SoundSentryProc  (preliminary−Windows NT)

The SoundSentryProc function is a library-defined callback function that produces a customized visual signal when the SoundSentry accessibility feature is on and a Windows-based application (or a non-Windows-based application running in a window) generates a sound through the computer's built-in speaker.

LRESULT CALLBACK SoundSentryProc(

DWORD  dwMillisec,	// duration of visual signal
DWORD  fdwEffect	// effect-type flag
);
Parameters

dwMillisec

Specifies the duration, in milliseconds, of the visual signal that is displayed when a Windows-based application (or a non-Windows-based application running in a window) generates a sound.

fdwEffect

Specifies the type of visual signal to display. Currently, this value must always be SSWF_CUSTOM.

Return Value

If the visual signal was or will be displayed correctly, the return value is TRUE. If the signal is asynchronous and the status is not available when the function is called, it should return TRUE.

If an error prevented the signal from being displayed, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The library that contains the SoundSentryProc function must be a 32-bit DLL, and the DLL must export a function with the name "SoundSentryProc."

The SoundSentryProc function is called only after an application or library calls the SystemParametersInfo function, specifying the SPI_SETSOUNDSENTRY value and the address of a SOUNDSENTRY structure whose iWindowsEffect member is set to SSWF_CUSTOM.

See Also

SOUNDSENTRY, SystemParametersInfo


StartDoc

The StartDoc function starts a print job. This function replaces the STARTDOC printer escape.

int StartDoc(

HDC  hdc,	// handle of device context
CONST DOCINFO *  lpdi	// address of structure with file names
);
Parameters

hdc

Identifies the device context for the print job.

lpdi

Points to a DOCINFO structure containing the name of the document file and the name of the output file.

Return Value

If the function succeeds, the return value is greater than zero. This value is the print job identifier for the document.

If the function fails, the return value is less than or equal to zero. To get extended error information, call GetLastError.

Remarks

Applications should call the StartDoc function immediately before beginning a print job. Using this function ensures that multipage documents are not interspersed with other print jobs.

Applications can use the value returned by StartDoc to retrieve or set the priority of a print job. Call the GetJob or SetJob function and supply this value as one of the required arguments.

See Also

DOCINFO, EndDoc, GetJob, SetJob


StartDocPrinter

The StartDocPrinter function informs the print spooler that a document is to be spooled for printing.

DWORD StartDocPrinter(

HANDLE  hPrinter,	// handle of printer object
DWORD  dwLevel,	// structure level
LPBYTE  lpbDocInfo	// address of structure
);
Parameters

hPrinter

Identifies the printer.

dwLevel

Specifies the version of the structure to which lpbDocInfo points. This value must be 1 for Windows NT. For Windows 95, you can also select a value of 2. (See DOC_INFO_2 following.)

lpbDocInfo

Points to a DOC_INFO_1 structure or a DOC_INFO_2 structure. If dwlevel is 1, the function stores the data in a DOC_INFO_1 structure. If dwlevel is 2, the function stores the data in a DOC_INFO_2 structure.

Windows 95 only: The DOC_INFO_2 structure has the following form:

typedef struct _DOC_INFO_2 { // dci2

    LPTSTR pDocName;

    LPTSTR pOutputFile;

    LPTSTR pDatatype;

    DWORD dwMode;

    DWORD JobId;

} DOC_INFO_2;

Return Value

If the function succeeds, the return value identifies the print job.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The printer handle identified by the hPrinter parameter is obtained by calling the OpenPrinter function.

The return value will never be greater than 2^31 − 1.

See Also

DOC_INFO_1, OpenPrinter


StartPage

The StartPage function prepares the printer driver to accept data.

int StartPage(

HDC  hDC	// handle of device context
);
Parameters

hDC

Identifies the device context for the print job.

Return Value

If the function succeeds, the return value is greater than zero.

If the function fails, the return value is less than or equal to zero. To get extended error information, call GetLastError.

Remarks

The system disables the ResetDC function between calls to the StartPage and EndPage functions. This means that an application cannot change the device mode except at page boundaries.

See Also

EndPage, ResetDC


StartPagePrinter

The StartPagePrinter function informs the spooler that a page is about to be printed on the specified printer.

BOOL StartPagePrinter(

HANDLE  hPrinter	// handle of printer object
);
Parameters

hPrinter

Identifies a printer.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The printer handle identified by the hPrinter parameter is obtained by calling the OpenPrinter function.

When an application has finished writing a page, it should call the EndPagePrinter function to inform the spooler that the page is complete.

See Also

EndPagePrinter, OpenPrinter


StartService

The StartService function starts the execution of a service.

BOOL StartService(

SC_HANDLE  schService,	// handle of service
DWORD  dwNumServiceArgs,	// number of arguments
LPCTSTR  *lpszServiceArgs	// address of array of argument string pointers
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error codes can be set by the service control manager. Others can be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_ACCESS_DENIED	The specified handle was not opened with SERVICE_START access.
ERROR_INVALID_HANDLE	The specified handle is invalid.
ERROR_PATH_NOT_FOUND	The service binary file could not be found.
ERROR_SERVICE_ALREADY_RUNNING	An instance of the service is already running.
ERROR_SERVICE_DATABASE_LOCKED	The database is locked.
ERROR_SERVICE_DEPENDENCY_DELETED	The service depends on a service that does not exist or has been marked for deletion.
ERROR_SERVICE_DEPENDENCY_FAIL	The service depends on another service that has failed to start.
ERROR_SERVICE_DISABLED	The service has been disabled.
ERROR_SERVICE_LOGON_FAILED	The service could not be logged on.
ERROR_SERVICE_MARKED_FOR_DELETE	The service has been marked for deletion.
ERROR_SERVICE_NO_THREAD	A thread could not be created for the Win32 service.
ERROR_SERVICE_REQUEST_TIMEOUT	The service did not respond to the start request in a timely fashion.
Remarks

When a driver service is started, the StartService function does not return until the device driver has finished initializing.

When a 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, ServiceMain


StartServiceCtrlDispatcher

The StartServiceCtrlDispatcher function connects the main thread of a service process to the service control manager, which causes the thread to be the service control dispatcher thread for the calling process.

BOOL StartServiceCtrlDispatcher(

LPSERVICE_TABLE_ENTRY  lpsteServiceTable	// address of service table
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error code can be set by the service control manager. Other error codes can be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_INVALID_DATA	The specified dispatch table contains entries that are not in the proper format.
Remarks

When the service control manager starts a service process, it waits for the process to call the StartServiceCtrlDispatcher function. The main thread of a service process should make this call as soon as possible after it starts up. If StartServiceCtrlDispatcher succeeds, it connects the calling thread to the service control manager and does not return until all running services in the process have terminated. The service control manager uses this connection to send control and service start requests to the main thread of the service process. The main thread acts as a dispatcher by invoking the appropriate Handler function to handle control requests, or by creating a new thread to execute the appropriate ServiceMain function when a new service is started.

The 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, Handler, RegisterServiceCtrlHandler, ServiceMain, SERVICE_TABLE_ENTRY


StartSound

The StartSound function has been deleted.

See Also

Beep, MessageBeep


StopSound

The StopSound function has been deleted.

See Also

Beep, MessageBeep


StretchBlt

The StretchBlt function copies a bitmap from a source rectangle into a destination rectangle, stretching or compressing the bitmap to fit the dimensions of the destination rectangle, if necessary. Windows stretches or compresses the bitmap according to the stretching mode currently set in the destination device context.

BOOL StretchBlt(

HDC  hdcDest,	// handle of destination device context
int  nXOriginDest,	// x-coordinate of upper-left corner of dest. rect.
int  nYOriginDest,	// y-coordinate of upper-left corner of dest. rect.
int  nWidthDest,	// width of destination rectangle
int  nHeightDest,	// height of destination rectangle
HDC  hdcSrc,	// handle of source device context
int  nXOriginSrc,	// x-coordinate of upper-left corner of source rectangle
int  nYOriginSrc,	// y-coordinate of upper-left corner of source rectangle
int  nWidthSrc,	// width of source rectangle
int  nHeightSrc,	// height of source rectangle
DWORD  dwRop	// raster operation code
);
Parameters

hdcDest

Identifies the destination device context.

nXOriginDest

Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.

nYOriginDest

Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.

nWidthDest

Specifies the width, in logical units, of the destination rectangle.

nHeightDest

Specifies the height, in logical units, of the destination rectangle.

hdcSrc

Identifies the source device context.

nXOriginSrc

Specifies the x-coordinate, in logical units, of the upper-left corner of the source rectangle.

nYOriginSrc

Specifies the y-coordinate, in logical units, of the upper-left corner of the source rectangle.

nWidthSrc

Specifies the width, in logical units, of the source rectangle.

nHeightSrc

Specifies the height, in logical units, of the source rectangle.

dwRop

Specifies the raster operation to be performed. Raster operation codes define how Windows combines colors in output operations that involve a brush, a source bitmap, and a destination bitmap.

See the BitBlt function for a list of common raster operation codes.

Return Value

If the function was successful, the return value is TRUE.

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

Remarks

StretchBlt stretches or compresses the source bitmap in memory and then copies the result to the destination rectangle. The color data for pattern or destination pixels is merged after the stretching or compression occurs.

When an enhanced metafile is being recorded, an error occurs (and the function returns FALSE) if the source device context identifies an enhanced-metafile device context.

If the specified raster operation requires a brush, Windows uses the brush currently selected into the destination device context.

The destination coordinates are transformed by using the transformation currently specified for the destination device context; the source coordinates are transformed by using the transformation currently specified for the source device context.

If the source transformation has a rotation or shear, an error occurs.

If destination, source, and pattern bitmaps do not have the same color format, StretchBlt converts the source and pattern bitmaps to match the destination bitmap.

If StretchBlt must convert a monochrome bitmap to a color bitmap, it sets white bits (1) to the background color and black bits (0) to the foreground color. To convert a color bitmap to a monochrome bitmap, it sets pixels that match the background color to white (1) and sets all other pixels to black (0). The foreground and background colors of the device context with color are used.

StretchBlt creates a mirror image of a bitmap if the signs of the nWidthSrc and nWidthDest parameters or of the nHeightSrc and nHeightDest parameters differ. If nWidthSrc and nWidthDest have different signs, the function creates a mirror image of the bitmap along the x-axis. If nHeightSrc and nHeightDest have different signs, the function creates a mirror image of the bitmap along the y-axis.

Not all devices support the StretchBlt function. For more information, see the GetDeviceCaps function.

See Also

BitBlt, GetDeviceCaps, MaskBlt, PlgBlt, SetStretchBltMode


StretchDIBits

The StretchDIBits function copies the color data for a rectangle of pixels in a device-independent bitmap (DIB) to the specified destination rectangle. If the destination rectangle is larger than the source rectangle, this function stretches the rows and columns of color data to fit the destination rectangle. If the destination rectangle is smaller than the source rectangle, this function compresses the rows and columns by using the specified raster operation.

int StretchDIBits(

HDC  hdc,	// handle of device context
int  XDest,	// x-coordinate of upper-left corner of dest. rect.
int  YDest,	// y-coordinate of upper-left corner of dest. rect.
int  nDestWidth,	// width of destination rectangle
int  nDestHeight,	// height of destination rectangle
int  XSrc,	// x-coordinate of upper-left corner of source rect.
int  YSrc,	// y-coordinate of upper-left corner of source rect.
int  nSrcWidth,	// width of source rectangle
int  nSrcHeight,	// height of source rectangle
CONST VOID  *lpBits,	// address of bitmap bits
CONST BITMAPINFO *  lpBitsInfo,	// address of bitmap data
UINT  iUsage,	// usage
DWORD  dwRop	// raster operation code
);
Parameters

hdc

Identifies the destination device context.

XDest

Specifies the x-coordinate, in logical units, of the upper-left corner of the destination rectangle.

YDest

Specifies the y-coordinate, in logical units, of the upper-left corner of the destination rectangle.

nDestWidth

Specifies the width, in logical units, of the destination rectangle.

nDestHeight

Specifies the height, in logical units, of the destination rectangle.

XSrc

Specifies the x-coordinate, in pixels, of the source rectangle in the DIB.

YSrc

Specifies the y-coordinate, in pixels, of the source rectangle in the DIB.

nSrcWidth

Specifies the width, in pixels, of the source rectangle in the DIB.

nSrcHeight

Specifies the height, in pixels, of the source rectangle in the DIB.

lpBits

Points to the DIB bits, which are stored as an array of bytes.

lpBitsInfo

Points to a BITMAPINFO structure that contains information about the DIB.

iUsage

Specifies whether the bmiColors member of the BITMAPINFO structure was provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or indices. The iUsage parameter must be one of the following values:

Value	Description
DIB_PAL_COLORS	The array contains 16-bit indices into the logical palette of the source device context.
DIB_RGB_COLORS	The color table contains literal RGB values.
dwRop

Specifies how the source pixels, the destination device context's current brush, and the destination pixels are to be combined to form the new image.

Return Value

If the function succeeds, the return value is the number of scan lines copied.

If the function fails, the return value is GDI_ERROR. To get extended error information, call GetLastError.

Remarks

The origin of a bottom-up DIB is the bottom-left corner; the origin of a top-down DIB is the upper-left corner.

StretchDIBits creates a mirror image of a bitmap if the signs of the nSrcWidth and nDestWidth parameters, or of the nSrcHeight and nDestHeight parameters differ. If nSrcWidth and nDestWidth have different signs, the function creates a mirror image of the bitmap along the x-axis. If nSrcHeight and nDestHeight have different signs, the function creates a mirror image of the bitmap along the y-axis.

See Also

SetMapMode, SetStretchBltMode, BITMAPINFO


StrokeAndFillPath

The StrokeAndFillPath function closes any open figures in a path, strokes the outline of the path by using the current pen, and fills its interior by using the current brush.

BOOL StrokeAndFillPath(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

The device context identified by the hdc parameter must contain a closed path.

The StrokeAndFillPath function has the same effect as closing all the open figures in the path, and stroking and filling the path separately, except that the filled region will not overlap the stroked region even if the pen is wide.

See Also

BeginPath, FillPath, SetPolyFillMode, StrokePath


StrokePath

The StrokePath function renders the specified path by using the current pen.

BOOL StrokePath(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies a device context that contains a closed path.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

The device context identified by the hdc parameter must contain a closed path.

See Also

BeginPath, EndPath , ExtCreatePen


SubtractRect

The SubtractRect function obtains the coordinates of a rectangle determined by subtracting one rectangle from another.

BOOL SubtractRect(

LPRECT  lprcDest,	// pointer to destination rectangle
CONST RECT *  lprcSrc1,	// pointer to rectangle to subtract from
CONST RECT *  lprcSrc2	// pointer to rectangle to subtract
);
Parameters

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 by lprcSrc1.

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero.

Remarks

The function only subtracts the rectangle specified by lprcSrc2 from the rectangle specified by lprcSrc1 when the rectangles intersect completely in either the x- or y-direction. For example, if *lprcSrc1 has the coordinates (10,10,100,100) and *lprcSrc2 has the coordinates (50,50,150,150), the function sets the coordinates of the rectangle pointed to by 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, RECT, UnionRect


SuspendThread

The SuspendThread function suspends the specified thread.

DWORD SuspendThread(

HANDLE  hThread	// handle to the thread
);
Parameters

hThread

Identifies the thread. The handle must have THREAD_SUSPEND_RESUME access.

Return Value

If the function succeeds, the return value is the thread's previous suspend count; otherwise, it is 0xFFFFFFFF. To get extended error information, use the GetLastError function.

Remarks

If the function succeeds, execution of the specified thread is suspended and the thread's suspend count is incremented.

Suspending a thread causes the thread to stop executing user-mode (application) code.

Each thread has a suspend count (with a maximum value of MAXIMUM_SUSPEND_COUNT). If the suspend count is greater than zero, the thread is suspended; otherwise, the thread is not suspended and is eligible for execution. Calling SuspendThread causes the target thread's suspend count to be incremented. Attempting to increment past the maximum suspend count causes an error without incrementing the count.

The ResumeThread function decrements the suspend count of a suspended thread.

See Also

ResumeThread


SwapMouseButton

The SwapMouseButton function reverses or restores the meaning of the left and right mouse buttons.

BOOL SwapMouseButton(

BOOL  fSwap	// reverse or restore buttons
);
Parameters

fSwap

Specifies whether the mouse button meanings are reversed or restored. If this parameter is TRUE, the left button generates right-button messages and the right button generates left-button messages. If this parameter is FALSE, the buttons are restored to their original meanings.

Return Value

If the meaning of the mouse buttons was reversed previously, before the function was called, the return value is TRUE.

If the meaning of the mouse buttons was not reversed, the return value is FALSE.

Remarks

Button swapping is provided as a convenience to people who use the mouse with their left hands. The SwapMouseButton function is usually called by Control Panel only. Although an application is free to call the function, the mouse is a shared resource and reversing the meaning of its buttons affects all applications.

See Also

SetDoubleClickTime


SwitchDesktop  (preliminaryWindows NT)
SwitchDesktop  (preliminary−Windows NT)

The SwitchDesktop function makes a desktop visible and activates it. This enables the desktop to receive input from the user. The calling process must have DESKTOP_SWITCHDESKTOP access to the desktop for the SwitchDesktop function to succeed.

BOOL SwitchDesktop(

HDESK hDesk	// handle of desktop to activate
);
Parameters

hDesk

Identifies the desktop to be made visible and active. This handle is returned by the CreateDesktop and OpenDesktop functions.

The SwitchDesktop function will fail if the desktop belongs to an invisible window station.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreateDesktop, OpenDesktop


SwitchStackBack

The SwitchStackBack function is not implemented in the Win32 API. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


SwitchStackTo

The SwitchStackTo function is not implemented in the Win32 API. Win32-based applications should use the VirtualLock and VirtualUnlock functions.


SyncAllVoices

The SyncAllVoices function has been deleted.

See Also

Beep, MessageBeep


SysMsgProc

The SysMsgProc hook procedure is a library-defined callback function the system calls after an input event occurs in a dialog box, message box, menu, or scroll bar, but before the message generated by the input event is processed. The hook procedure can monitor messages for any dialog box, message box, menu, or scroll bar in the system.

LRESULT CALLBACK SysMsgProc(

int  nCode,	// message flag
WPARAM  wParam,	// undefined
LPARAM  lParam	// address of structure with message data
);
Parameters

nCode

Specifies the type of input event that generated the message. This parameter can be one of the following values:

Value	Meaning
MSGF_DIALOGBOX	The input event occurred in a message box or dialog box.
MSGF_MENU	The input event occurred in a menu.
MSGF_SCROLLBAR	The input event occurred in a scroll bar.
MSGF_NEXTWINDOW	The input event occurred as a result of the user's pressing the ALT+TAB key combination to activate a different window.
If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies a NULL value.

lParam

Points to an MSG message structure.

Return Value

If the hook procedure processes the message, the return value must be nonzero. Otherwise, it must be zero.

Remarks

An application installs the hook procedure by specifying the WH_SYSMSGFILTER hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

SysMsgProc is a placeholder for the library-defined function name.

See Also

CallNextHookEx, MSG, SetWindowsHookEx


SystemParametersInfo

The SystemParametersInfo function queries or sets systemwide parameters. This function can also update the user profile while setting a parameter.

BOOL SystemParametersInfo(

UINT  uiAction,	// system parameter to query or set
UINT  uiParam,	// depends on action to be taken
PVOID  pvParam,	// depends on action to be taken
UINT  fWinIni	// user profile update flag
);
Parameters

uiAction

Specifies the systemwide parameter to query or set. This parameter can be one of the following values:

Value	Meaning
SPI_GETACCESSTIMEOUT	Retrieves information about the time-out period associated with the accessibility features. The uiParam parameter specifies the size of an ACCESSTIMEOUT structure, and pvParam points to the ACCESSTIMEOUT structure that receives the information.
SPI_GETANIMATION	Windows 95 only: Retrieves the animation effects associated with user actions. The pvParam parameter is the pointer to an ANIMATIONINFO structure that contains the retrieved metrics.
SPI_GETBEEP	Determines whether the warning beeper is on (TRUE) or off (FALSE). The pvParam parameter points to a BOOL variable.
SPI_GETBORDER	Retrieves the border multiplier factor that determines the width of a window's sizing border. The pvParam parameter points to an integer variable.
SPI_GETDEFAULTINPUTLANG	Windows 95 only: Returns the keyboard layout handle for the system default input language. The uiParam is not used. The pvParam parameter points to the 32-bit variable that receives the keyboard layout handle for the default language.
SPI_GETDRAGFULLWINDOWS	Windows 95 only: Determines whether dragging of full windows is enabled. The pvParam parameter points to a BOOL variable that receives TRUE if enabled, or FALSE otherwise.
SPI_GETFASTTASKSWITCH	Determines whether fast task switching is enabled. The pvParam parameter points to a BOOL variable that receives TRUE if enabled, or FALSE otherwise.
SPI_GETFILTERKEYS	Retrieves information about the FilterKeys accessibility feature. The uiParam parameter specifies the size of the FILTERKEYS structure, and pvParam points to the FILTERKEYS structure that receives the information.
SPI_GETGRIDGRANULARITY	Retrieves the current granularity value of the desktop sizing grid. The pvParam parameter points to an integer variable that receives the granularity.
SPI_GETHIGHCONTRAST	Windows 95 only: Retrieves information about the HighContrast accessibility feature. The pvParam parameter is the pointer to the HIGHCONTRAST structure that receives the information.
SPI_GETICONMETRICS	Windows 95 only: Retrieves the metrics associated with icons. The pvParam parameter points to the ICONMETRICS structure to fill in.
SPI_GETICONTITLELOGFONT	Retrieves the logical font information for the current icon-title font. The uiParam parameter specifies the size of a LOGFONT structure, and the pvParam parameter points to the LOGFONT structure to fill in.
SPI_GETICONTITLEWRAP	Determines whether icon-title wrapping is enabled. The pvParam parameter points to a BOOL variable that receives TRUE if enabled, or FALSE otherwise.
SPI_GETKEYBOARDDELAY	Retrieves the keyboard repeat-delay setting. The pvParam parameter points to an integer variable that receives the setting.
SPI_GETKEYBOARDPREF	Windows 95 only: Determines whether the user relies on the keyboard instead of the mouse, and wants applications to display keyboard interfaces that would otherwise be hidden. The uiParam parameter points to a BOOL variable that receives TRUE if the user relies on the keyboard; the variable receives FALSE otherwise.
SPI_GETKEYBOARDSPEED	Retrieves the keyboard repeat-speed setting. The pvParam parameter points to a DWORD variable that receives the setting.
SPI_GETLOWPOWERACTIVE	Windows 95 only: Determines whether the low-power phase of screen saving is enabled or not. The pvParam parameter points to a BOOL variable that receives TRUE if enabled, or FALSE if disabled.
SPI_GETLOWPOWERTIMEOUT	Windows 95 only: Retrieves the time-out value for the low-power phase of screen saving. The pvParam parameter points to an integer value that receives the value.
SPI_GETMENUDROPALIGNMENT	Determines whether pop-up menus are left-aligned or right-aligned, relative to the corresponding menu-bar item. The pvParam parameter points to a BOOL variable that receives TRUE if left-aligned, or FALSE otherwise.
SPI_GETMINIMIZEDMETRICS	Windows 95 only: Retrieves the metrics associated with minimized windows. The uiParam parameter specifies the size of the MINIMIZEDMETRICS structure. The pvParam parameter points to the MINIMIZEDMETRICS structure to fill in.
SPI_GETMOUSE	Retrieves the mouse thresholds and speed. The pvParam parameter points to an array of three integers that receives the two mouse threshholds and the mouse speed.
SPI_GETMOUSEKEYS	Retrieves information about the MouseKeys accessibility feature. The uiParam parameter specifies the size of a MOUSEKEYS structure, and pvParam points to the MOUSEKEYS structure that receives the information.
SPI_GETNONCLIENTMETRICS	Windows 95 only: Retrieves the metrics associated with the nonclient area of nonminimized windows. The pvParam parameter points to the NONCLIENTMETRICS structure to fill in.
SPI_GETPOWEROFFACTIVE	Windows 95 only: Determines whether the power-off phase of screen saving is enabled or not. The pvParam parameter points to a BOOL variable that receives TRUE if enabled, or FALSE if disabled.
SPI_GETPOWEROFFTIMEOUT	Windows 95 only: Retrieves the time-out value for the power-off phase of screen saving. The pvParam parameter points to an integer value that receives the value.
SPI_GETSCREENREADER	Windows 95 only: Determines whether a screen reviewer utility is running (TRUE) or not (FALSE). A screen reviewer utility directs textual information to an output device, such as a speech synthesizer or Braille display. When this flag is set, an application should provide textual information in situations where it would otherwise present the information graphically. The pvParam parameter points to a BOOL variable.
SPI_GETSCREENSAVEACTIVE	Determines whether screen saving is enabled. The pvParam parameter points to a BOOL variable that receives TRUE if enabled, or FALSE otherwise.
SPI_GETSCREENSAVETIMEOUT	Retrieves the screen saver time-out value, in seconds. The pvParam parameter points to an integer variable that receives the value.
SPI_GETSERIALKEYS	Windows 95 only: Retrieves information about the SerialKeys accessibility feature. The pvParam parameter points to the SERIALKEYS structure that receives the information.
SPI_GETSHOWSOUNDS	Determines whether the user requires an application to present information visually in situations where it would otherwise present the information only in audible form. The uiParam parameter points to a BOOL variable. Using this value is equivalent to calling GetSystemMetrics (SM_GETSHOWSOUNDS). That is the recommended call.
SPI_GETSOUNDSENTRY	Retrieves information about the SoundSentry accessibility feature. The uiParam parameter specifies the size of a SOUNDSENTRY structure, and pvParam points to the SOUNDSENTRY structure that receives the information.
SPI_GETSTICKYKEYS	Retrieves information about the MouseKeys accessibility feature. The uiParam parameter specifies the size of a STICKYKEYS structure, and pvParam points to the STICKYKEYS structure that receives the information.
SPI_GETTOGGLEKEYS	Retrieves information about the ToggleKeys accessibility feature. The uiParam parameter specifies the size of a TOGGLEKEYS structure, and pvParam points to the TOGGLEKEYS structure that receives the information.
SPI_GETWORKAREA	Windows 95 only: Retrieves the size of the working area. The working area is the portion of the screen not obscured by the tray. The pvParam parameter points to the RECT structure that receives the coordinates of the working area.
SPI_ICONHORIZONTALSPACING	Sets the width of an icon cell. The uiParam parameter specifies the width, in pixels.
SPI_ICONVERTICALSPACING	Sets the height of an icon cell. The uiParam parameter specifies the height, in pixels.
SPI_LANGDRIVER	Identifies the language driver. The pvParam parameter points to a character array that receives the filename of the language driver.
SPI_SETACCESSTIMEOUT	Sets the time-out period associated with the accessibility features. The uiParam parameter specifies the size of the ACCESSTIMEOUT structure, and pvParam points to the ACCESSTIMEOUT structure that contains the new parameters.
SPI_SETANIMATION	Windows 95 only: Sets the animation effects associated with user actions. The pvParam parameter points to an ANIMATIONINFO structure that contains the new metrics.
SPI_SETBEEP	Turns the warning beeper on or off. The uiParam parameter specifies TRUE for on, or FALSE for off.
SPI_SETBORDER	Sets the border multiplier factor that determines the width of a window's sizing border. The uiParam parameter specifies the new value.
SPI_SETDEFAULTINPUTLANG	Windows 95 only: Sets the default input language for the system shell and applications. The specified language must be displayable using the current system character set. The uiParam parameter is not used. The pvParam parameter points to a 32-bit variable that contains the keyboard layout handle for the default language.
SPI_SETDESKPATTERN	Sets the current desktop pattern by causing Windows to read the Pattern= setting from the WIN.INI file.
SPI_SETDESKWALLPAPER	Sets the desktop wallpaper. The pvParam parameter points to a null-terminated string containing the name of a bitmap file.
SPI_SETDOUBLECLICKTIME	Sets the double-click time for the mouse to the value of the uiParam parameter. The double-click time is the maximum number of milliseconds that can occur between the first and second clicks of a double-click.
SPI_SETDOUBLECLKHEIGHT	Sets the height of the double-click rectangle to the value of the uiParam parameter. The double-click rectangle is the rectangle within which the second click of a double-click must fall for it to be registered as a double-click.
SPI_SETDOUBLECLKWIDTH	Sets the width of the double-click rectangle to the value of the uiParam parameter. The double-click rectangle is the rectangle within which the second click of a double-click must fall for it to be registered as a double-click.
SPI_SETDRAGFULLWINDOWS	Windows 95 only: Sets dragging of full windows either on or off. The uiParam parameter specifies TRUE for on, or FALSE for off.
SPI_SETDRAGHEIGHT	Windows 95 only: Sets the height, in pixels, of the rectangle used to detect the start of a drag operation.
SPI_SETDRAGWIDTH	Windows 95 only: Sets the width, in pixels, of the rectangle used to detect the start of a drag operation.
SPI_SETFASTTASKSWITCH	Turns fast task switching on or off. The uiParam parameter specifies TRUE for on, or FALSE for off.
SPI_SETFILTERKEYS	Sets the parameters of the FilterKeys accessibility feature. The uiParam parameter specifies the size of the FILTERKEYS structure, and pvParam points to the FILTERKEYS structure that contains the new parameters.
SPI_SETGRIDGRANULARITY	Sets the granularity of the desktop sizing grid to the value of the uiParam parameter.
SPI_SETHIGHCONTRAST	Windows 95 only: Sets the parameters of the HighContrast accessibility feature. The pvParam parameter is the address of the HIGHCONTRAST structure that contains the new parameters.
SPI_SETICONMETRICS	Windows 95 only: Sets the metrics associated with icons. The pvParam parameter points to an ICONMETRICS structure that contains the new metrics.
SPI_SETICONTITLELOGFONT	Sets the font that is used for icon titles. The uiParam parameter specifies the size of a LOGFONT structure, and the lParam parameter points to a LOGFONT structure.
SPI_SETICONTITLEWRAP	Turns icon-title wrapping on or off. The uiParam parameter specifies TRUE for on, or FALSE for off.
SPI_SETKEYBOARDDELAY	Sets the keyboard repeat-delay setting to the value of the uiParam parameter.
SPI_SETKEYBOARDPREF	Windows 95 only: Sets the keyboard preference. The uiParam parameter specifies TRUE if the user relies on the keyboard instead of the mouse, and wants applications to display keyboard interfaces that would otherwise be hidden; uiParam is FALSE otherwise.
SPI_SETKEYBOARDSPEED	Sets the keyboard repeat-speed setting to the value of the uiParam parameter.
SPI_SETLANGTOGGLE	Windows 95 only: Sets the hot key set for switching between input languages. The uiParam and pvParam parameters are not used. The value sets the shortcut keys in the keyboard property sheets by reading the registry again. The registry must be set before this flag is used. the path in the registry is \HKEY_CURRENT_USER\keyboard layout\toggle. Valid values are "1" = alt+shift, "2" = ctrl+shift, and "3" = none.
SPI_SETLOWPOWERACTIVE	Windows 95 only: Activates or deactivates the low-power phase of screen saving. Set uiParam to 1 to activate, or 0 to deactivate. The pvParam parameter must be NULL.
SPI_SETLOWPOWERTIMEOUT	Windows 95 only: Retrieves the time-out value, in seconds, for the low-power phase of screen saving. The uiParam parameter specifies the new value. The pvParam parameter must be NULL.
SPI_SETMENUDROPALIGNMENT	Sets the alignment value of pop-up menus. The uiParam parameter specifies TRUE for right alignment, or FALSE for left alignment.
SPI_SETMINIMIZEDMETRICS	Windows 95 only: Sets the metrics associated with minimized windows. The pvParam parameter points to a MINIMIZEDMETRICS structure that contains the new metrics.
SPI_SETMOUSE	Sets the mouse thresholds and speed. The pvParam parameter points to an array of three integers that specifies the two mouse thresholds and the mouse speed.
SPI_SETMOUSEBUTTONSWAP	Swaps or restores the meaning of the left and right mouse buttons. The uiParam parameter specifies TRUE to swap the meanings of the buttons, or FALSE to to restore their original meanings.
SPI_SETMOUSEKEYS	Sets the parameters of the MouseKeys accessibility feature. The uiParam parameter specifies the size of the MOUSEKEYS structure, and pvParam points to the MOUSEKEYS structure that contains the new parameters.
SPI_SETNONCLIENTMETRICS	Windows 95 only: Sets the metrics associated with the nonclient area of nonminimized windows. The pvParam parameter is the address of a NONCLIENTMETRICS structure that contains the new metrics.
SPI_SETPENWINDOWS	Windows 95 only: Specifies that pen windows is being loaded or unloaded. The uiParam parameter is TRUE when loading and FALSE when unloading pen windows. The lParam parameter is NULL.
SPI_SETPOWEROFFACTIVE	Windows 95 only: Activates or deactivates the  power-off phase of screen saving. Set uiParam to 1 to activate, or 0 to deactivate. The pvParam parameter must be NULL.
SPI_SETPOWEROFFTIMEOUT	Windows 95 only: Retrieves the time-out value, in seconds, for the power-off phase of screen saving. The uiParam parameter specifies the new value. The pvParam parameter must be NULL.
SPI_SETSCREENREADER	Windows 95 only: Indicates whether a screen review utility is running. The uiParam parameter specifies TRUE for on, or FALSE for off.
SPI_SETSCREENSAVEACTIVE	Sets the state of the screen saver. The uiParam parameter specifies TRUE to activate screen saving, or FALSE to deactivate it.
SPI_SETSCREENSAVETIMEOUT	Sets the screen saver time-out value to the value of the uiParam parameter. This value is the amount of time, in seconds, that the system must be idle before the screen saver activates.
SPI_SETSERIALKEYS	Windows 95 only: Sets the parameters of the SerialKeys accessibility feature. The pvParam parameter is the address of the SERIALKEYS structure that contains the new parameters.
SPI_SETSHOWSOUNDS	Sets the ShowSounds accessibility feature as on or off. The uiParam parameter specifies TRUE for on, or FALSE for off.
SPI_SETSOUNDSENTRY	Sets the parameters of the SoundSentry accessibility feature. The uiParam parameter specifies the size of the SOUNDSENTRY structure, and pvParam points to the SOUNDSENTRY structure that contains the new parameters.
SPI_SETSTICKYKEYS	Sets the parameters of the StickyKeys accessibility feature. The uiParam parameter specifies the size of the STICKYKEYS structure, and pvParam points to the STICKYKEYS structure that contains the new parameters.
SPI_SETTOGGLEKEYS	Sets the parameters of the ToggleKeys accessibility feature. The uiParam parameter specifies the size of the TOGGLEKEYS structure, and pvParam points to the TOGGLEKEYS structure that contains the new parameters.
SPI_SETWORKAREA	Windows 95 only: Sets the size of the working area. The working area is the portion of the screen not obscured by the tray. The pvParam parameter points to the RECT structure that contains the coordinates of the working area.
uiParam

Depends on the system parameter being queried or set. For more information about systemwide parameters, see the uiAction parameter. If not otherwise indicated, specify zero.

pvParam

Depends on the system parameter being queried or set. For more information about systemwide parameters, see the uiAction parameter. If not otherwise indicated, specify zero.

fWinIni

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 zero or can be one of the following values:

Value	Action
SPIF_UPDATEINIFILE	Writes the new system-wide parameter setting to the user profile.
SPIF_SENDWININICHANGE	Broadcasts the WM_WININICHANGE message after updating the user profile.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

This function is intended for use with applications, such as Control Panel, that allow the user to customize the Windows environment.

A keyboard layout name should be derived from the hexadecimal value of the language identifier corresponding to the layout. For example, U.S. English has a language identifier of 0x0409, so the primary U.S. English layout is named "00000409." Variants of U.S. English layout, such as the Dvorak layout, are named "00010409," "00020409" and so on. For a list of the primary language identifiers and sublanguage identifiers that make up a language identifier, see the MAKELANGID macro.

See Also

ACCESSTIMEOUT, ANIMATIONINFO, FILTERKEYS, GetLastError, GetSystemMetrics, HIGHCONTRAST, ICONMETRICS, LOGFONT, MAKELANGID, MINIMIZEDMETRICS, MOUSEKEYS, NONCLIENTMETRICS, RECT, SERIALKEYS, SOUNDSENTRY, STICKYKEYS, TOGGLEKEYS, WM_WININICHANGE


SystemTimeToFileTime

The SystemTimeToFileTime function converts a system time to a file time.

BOOL SystemTimeToFileTime(

CONST SYSTEMTIME *  lpst,	// address of system time to convert
LPFILETIME  lpft	// address of buffer for converted file time
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

DosDateTimeToFileTime, FILETIME, FileTimeToDosDateTime, FileTimeToSystemTime, SYSTEMTIME


SystemTimeToTzSpecificLocalTime

The SystemTimeToTzSpecificLocalTime function converts a Coordinated Universal Time (UTC) to a specified time zone's corresponding local time.

BOOL SystemTimeToTzSpecificLocalTime (

LPTIME_ZONE_INFORMATION  lpTimeZoneInformation,	// pointer to time zone of interest
LPSYSTEMTIME  lpUniversalTime,	// pointer to universal time of interest
LPSYSTEMTIME  lpLocalTime	// pointer to structure to receive local time
);
Parameters

lpTimeZoneInformation

Pointer to a TIME_ZONE_INFORMATION structure that specifies the time zone of interest.

If lpTimeZoneInformation is NULL, the function uses the currently active time zone.

lpUniversalTime

Pointer to a SYSTEMTIME structure that specifies a UTC. The function converts this universal time to the specified time zone's corresponding local time.

lpLocalTime

Pointer to a SYSTEMTIME structure that receives the local time information.

Return Value

If the function succeeds, the return value is TRUE, and the function sets the members of the SYSTEMTIME structure pointed to by lpLocalTime to the appropriate local time values.

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

Remarks

The SystemTimeToTzSpecificLocalTime function works in Windows NT. If called in Windows 95, the function fails, and returns FALSE.

See Also

GetSystemTime, GetTimeZoneInformation, SYSTEMTIME, TIME_ZONE_INFORMATION


TabbedTextOut

The TabbedTextOut function writes a character string at a specified location, expanding tabs to the values specified in an array of tab-stop positions. Text is written in the currently selected font.

LONG TabbedTextOut(

HDC  hdc,	// handle of device context
int  x,	// x-coordinate of starting position
int  y,	// y-coordinate of starting position
LPCTSTR  lpString,	// address of string
int  nCount,	// number of characters in string
int  nTabPositions,	// number of tabs in array
LPINT  lpnTabStopPositions,	// address of array for tab positions
int  nTabOrigin	// x-coordinate for tab expansion
);
Parameters

hdc

Identifies the device context.

x

Specifies the x-coordinate of the starting point of the string, in logical units.

y

Specifies the y-coordinate of the starting point of the string, in logical units.

lpString

Points to the character string to draw. The string does not need to be zero-terminated, since nCount specifies the length of the string.

nCount

Specifies the number of characters in the string.

nTabPositions

Specifies the number of values in the array of tab-stop positions.

lpnTabStopPositions

Points to an array containing the tab-stop positions, in device units. The tab stops must be sorted in increasing order; the smallest x-value should be the first item in the array.

Windows 95 only: A tab stop can be specified as a negative value, which causes text to be right-aligned on the tab stop rather than left-aligned.

nTabOrigin

Specifies the x-coordinate of the starting position from which tabs are expanded, in logical units.

Return Value

If the function succeeds, the return value is the dimensions, in logical units, of the string. The height is in the high-order word and the width is in the low-order word.

Remarks

If the nTabPositions parameter is zero and the lpnTabStopPositions parameter is NULL, tabs are expanded to eight times the average character width.

If nTabPositions is 1, the tab stops are separated by the distance specified by the first value in the lpnTabStopPositions array.

If the lpnTabStopPositions array contains more than one value, a tab stop is set for each value in the array, up to the number specified by nTabPositions.

The nTabOrigin parameter allows an application to call the TabbedTextOut function several times for a single line. If the application calls TabbedTextOut more than once with the nTabOrigin set to the same value each time, the function expands all tabs relative to the position specified by nTabOrigin.

By default, the current position is not used or updated by the TabbedTextOut function. If an application needs to update the current position when it calls TabbedTextOut, the application can call the SetTextAlign function with the wFlags parameter set to TA_UPDATECP. When this flag is set, Windows ignores the x and y parameters on subsequent calls to the TabbedTextOut function, using the current position instead.

See Also

DrawText, GetTabbedTextExtent, GrayString, SetTextAlign, TextOut


TerminateProcess

The TerminateProcess function terminates the specified process and all of its threads.

BOOL TerminateProcess(

HANDLE  hProcess,	// handle to the process
UINT  uExitCode	// exit code for the process
);
Parameters

hProcess

Identifies the process to terminate. 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 value. Use the GetExitCodeThread function to retrieve a thread's exit value.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The TerminateProcess function is used to unconditionally cause a process to exit. Use it only in extreme circumstances. The state of global data maintained by dynamic-link libraries (DLLs) may be compromised if TerminateProcess is used rather than ExitProcess.

TerminateProcess causes all threads within a process to terminate, and causes a process to exit, but DLLs attached to the process are not notified that the process is terminating.

Terminating a process causes the following:

1.	All of the object handles opened by the process are closed.

2.	All of the threads in the process terminate their execution.

3.	The state of the process object becomes signaled, satisfying any threads that had been waiting for the process to terminate.

4.	The states of all threads of the process become signaled, satisfying any threads that had been waiting for the threads to terminate.

5.	The termination status of the process changes from STILL_ACTIVE to the exit value of the process.

Terminating a process does not cause child processes to be terminated.

Terminating a process does not necessarily remove the process object from the system. A process object is deleted when the last handle to the process is closed.

See Also

ExitProcess, OpenProcess, GetExitCodeProcess, GetExitCodeThread,


TerminateThread

The TerminateThread function terminates a thread.

BOOL TerminateThread(

HANDLE  hThread,	// handle to the thread
DWORD  dwExitCode	// exit code for the thread
);
Parameters

hThread

Identifies the thread to terminate. 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 value.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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, GetExitCodeThread


TextOut

The TextOut function writes a character string at the specified location, using the currently selected font.

BOOL TextOut(

HDC  hdc,	// handle of device context
int  nXStart,	// x-coordinate of starting position
int  nYStart,	// y-coordinate of starting position
LPCTSTR  lpString,	// address of string
int  cbString	// number of characters in string
);
Parameters

hdc

Identifies the device context.

nXStart

Specifies the logical x-coordinate of the reference point that Windows uses to align the string.

nYStart

Specifies the logical y-coordinate of the reference point that Windows uses to align the string.

lpString

Points to the string to be drawn. The string does not need to be zero-terminated, since cbString specifies the length of the string.

cbString

Specifies the number of characters in the string.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The interpretation of the reference point depends on the current text-alignment mode. An application can retrieve this mode by calling the GetTextAlign function; an application can alter this mode by calling the SetTextAlign function.

By default, the current position is not used or updated by this function. However, an application can call the SetTextAlign function with the fMode parameter set to TA_UPDATECP to permit Windows to use and update the current position each time the application calls TextOut for a specified device context. When this flag is set, Windows ignores the nXStart and nYStart parameters on subsequent TextOut calls.

When the TextOut function is placed inside a path bracket, the system generates a path for the TrueType text that includes each character plus its character box. The region generated is the character box minus the text, rather than the text itself. You can obtain the region enclosed by the outline of the TrueType text by setting the background mode to transparent before placing the TextOut function in the path bracket. Following is sample code that demonstrates this procedure.

// Obtain the window's client rectangle

GetClientRect(hwnd, &r);

// THE FIX: by setting the background mode

// to transparent, the region is the text itself

// SetBkMode(hdc, TRANSPARENT);

// Bracket begin a path

BeginPath(hdc);

// Send some text out into the world

TextOut(hdc, r.left, r.top, "Defenestration can be hazardous", 4);

// Bracket end a path

EndPath(hdc);

// Derive a region from that path

SelectClipPath(hdc, RGN_AND);

// This generates the same result as SelectClipPath()

// SelectClipRgn(hdc, PathToRegion(hdc));

// Fill the region with grayness

FillRect(hdc, &r, GetStockObject(GRAY_BRUSH));

See Also

GetTextAlign, SetTextAlign, TabbedTextOut


Throw

The Throw function is not implemented in the Win32 API.

Structured exception handling is built into the Win32 application programming interface.


TileWindows  (preliminaryWindows 95)
TileWindows  (preliminary−Windows 95)

The TileWindows function tiles the specified windows, or the child windows of the specified parent window.

WORD WINAPI TileWindows(

HWND hwndParent,	// handle of parent window
WORD wFlags,	// types of windows not to arrange
LPCRECT lpRect,	// rectangle to arrange windows in
WORD cChildrenb,	// number of windows to arrange
const HWND FAR *ahwndChildren	// array of window handles
);
Parameters

hwndParent

Identifies the parent window. If this parameter is NULL, the desktop window is assumed.

wFlags

Specifies the types of windows not to arrange, and whether to tile vertically or horizontally. This parameter can be one of the following values combined with zero or more of the values listed with the CascadeWindows function:

Value	Meaning
MDITILE_HORIZONTAL	Tiles windows horizontally.
MDITILE_VERTICAL	Tiles windows vertically.
lpRect

Points to a SMALL_RECT structure that specifies the rectangular area, in screen coordinates, within which the windows are arranged. If this parameter is NULL, the client area of the parent window is used.

cChildren

Specifies the number of elements in the array specified by the ahwndChildren parameter. This parameter is ignored if ahwndChildren is NULL.

ahwndChildren

Points to an array of window handles identifying the windows to arrange. If this parameter is NULL, the child windows of the specified parent window (or of the desktop window) are arranged.

Return Value

If the function succeeds, the return value is the number of windows arranged.

If the function fails, the return value is zero.

See Also

CascadeWindows, SMALL_RECT


TimerProc

The TimerProc function is an application-defined callback function that processes WM_TIMER messages.

VOID CALLBACK TimerProc(

HWND  hwnd,	// handle of window for timer messages
UINT  uMsg,	// WM_TIMER message
UINT  idEvent,	// timer identifier
DWORD  dwTime	// current system time
);
Parameters

hwnd

Identifies the window associated with the timer.

uMsg

Specifies the WM_TIMER message.

idEvent

Specifies the timer's identifier.

dwTime

Specifies the system time, in Coordinated Universal Time (UTC) format.

Return Value

This function does not return a value.

Remarks

TimerProc is a placeholder for the application-defined function name.

See Also

KillTimer, SetTimer, WM_TIMER


TlsAlloc

The TlsAlloc function allocates a thread local storage (TLS) index. Any thread of the process can subsequently use this index to store and retrieve values that are local to the thread.

DWORD TlsAlloc(VOID)

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is a TLS index.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

The threads of the process can use the TLS index in subsequent calls to the TlsFree, TlsSetValue, or TlsGetValue functions.

TLS indexes are typically allocated during process or dynamic-link library (DLL) initialization. Once allocated, each thread of the process can use a TLS index to access its own TLS storage slot. To store a value in its slot, a thread specifies the index in a call to TlsSetValue. The thread specifies the same index in a subsequent call to TlsGetValue, to retrieve the stored value.

The constant TLS_MINIMUM_AVAILABLE defines the minimum number of TLS indexes available in each process. This minimum is guaranteed to be at least 64 for all systems.

TLS indexes are not valid across process boundaries. A DLL cannot assume that an index assigned in one process is valid in another process.

A DLL might use TlsAlloc, TlsSetValue, TlsGetValue, and TlsFree as follows:

1.	When a DLL attaches to a process, the DLL uses TlsAlloc to allocate a TLS index. The DLL then allocates some dynamic storage and uses the TLS index in a call to TlsSetValue to store the address in the TLS slot. This concludes the per-thread initialization for the initial thread of the process. The TLS index is stored in a global or static variable of the DLL.

2.	Each time the DLL attaches to a new thread of the process, the DLL allocates some dynamic storage for the new thread and uses the TLS index in a call to TlsSetValue to store the address in the TLS slot. This concludes the per-thread initialization for the new thread.

3.	Each time an initialized thread makes a DLL call requiring the data in its dynamic storage, the DLL uses the TLS index in a call to TlsGetValue to retrieve the address of the dynamic storage for that thread.

See Also

TlsFree, TlsGetValue, TlsSetValue


TlsFree

The TlsFree function releases a thread local storage (TLS) index, making it available for reuse.

BOOL TlsFree(

DWORD  dwTlsIndex	// TLS index to free
);
Parameters

dwTlsIndex

Specifies a TLS index that was allocated by the TlsAlloc function.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the threads of the process have allocated dynamic storage and used the TLS index to store pointers to this storage, they should free the storage before calling TlsFree. The TlsFree function does not free any dynamic storage that has been associated with the TLS index. It is expected that DLLs call this function (if at all) only during their process detach routine.

For a brief discussion of typical uses of the TLS functions, see the Remarks section of the TlsAlloc function.

See Also

TlsAlloc, TlsGetValue, TlsSetValue


TlsGetValue

The TlsGetValue function retrieves the value in the calling thread's thread local storage (TLS) slot for a specified TLS index. Each thread of a process has its own slot for each TLS index.

LPVOID TlsGetValue(

DWORD  dwTlsIndex	// TLS index to retrieve value for
);
Parameters

dwTlsIndex

Specifies a TLS index that was allocated by the TlsAlloc function.

Return Value

If the function succeeds, the return value is the value stored in the calling thread's TLS slot associated with the specified index.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Note that the data stored in a TLS slot can have a value of zero. In this case, the return value is zero and GetLastError returns NO_ERROR.

Remarks

TLS indexes are typically allocated by the TlsAlloc function during process or DLL initialization. Once allocated, each thread of the process can use a TLS index to access its own TLS storage slot for that index. The storage slot for each thread is initialized to NULL. A thread specifies a TLS index in a call to TlsSetValue, to store a value in its slot. The thread specifies the same index in a subsequent call to TlsGetValue, to retrieve the stored value.

TlsSetValue and TlsGetValue were implemented with speed as the primary goal. These functions perform minimal parameter validation and error checking. In particular, this function succeeds if dwTlsIndex is in the range 0 through (TLS_MINIMUM_AVAILABLE − 1). It is up to the programmer to ensure that the index is valid.

Win32 functions that return indications of failure call SetLastError when they fail. They generally do not call SetLastError when they succeed. The TlsGetValue function is an exception to this general rule. The TlsGetValue function calls SetLastError to clear a thread's last error when it succeeds. That allows checking for the error-free retrieval of NULL values.

See Also

GetLastError, SetLastError, TlsAlloc, TlsFree, TlsSetValue


TlsSetValue

The TlsSetValue function stores a value in the calling thread's thread local storage (TLS) slot for a specified TLS index. Each thread of a process has its own slot for each TLS index.

BOOL TlsSetValue(

DWORD  dwTlsIndex,	// TLS index to set value for
LPVOID  lpvTlsValue	// value to be stored
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

TLS indexes are typically allocated by the TlsAlloc function during process or DLL initialization. Once allocated, each thread of the process can use a TLS index to access its own TLS storage slot for that index. The storage slot for each thread is initialized to NULL. A thread specifies a TLS index in a call to TlsSetValue, to store a value in its slot. The thread specifies the same index in a subsequent call to TlsGetValue, to retrieve the stored value.

TlsSetValue and TlsGetValue were implemented with speed as the primary goal. These functions perform minimal parameter validation and error checking. In particular, this function succeeds if dwTlsIndex is in the range 0 through (TLS_MINIMUM_AVAILABLE − 1). It is up to the programmer to ensure that the index is valid.

See Also

TlsAlloc, TlsFree, TlsGetValue


ToAscii

The ToAscii function translates the specified virtual-key code and keyboard state to the corresponding Windows character or characters.

int ToAscii(

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
);
Parameters

uVirtKey

Specifies the virtual-key code to be translated.

uScanCode

Specifies the hardware scan code of the key to be translated. The high-order bit of this value is set if the key is up.

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.

Return Value

If the specified key is a dead key, the return value is negative. Otherwise, it is one of the following values:

Value	Meaning
0	The specified virtual key has no translation for the current state of the keyboard.
1	One Windows character was copied to the buffer.
2	Two characters were copied to the buffer. This usually happens when a dead-key character (accent or diacritic) stored in the keyboard layout cannot be composed with the specified virtual key to form a single character.
Remarks

The parameters supplied to the ToAscii function might not be sufficient to translate the virtual-key code, because a previous dead key is stored in the keyboard layout.

Typically, ToAscii performs the translation based on the virtual-key code. In some cases, however, bit 15 of the uScanCode parameter may be used to distinguish between a key press and a key release.

See Also

OemKeyScan, ToUnicode, VkKeyScan


ToAsciiEx  (preliminaryWindows 95)
ToAsciiEx  (preliminary−Windows 95)

The ToAsciiEx function translates the specified virtual-key code and keyboard state to the corresponding Windows character or characters. The function translates the code using the input language and physical keyboard layout identified by the given keyboard layout handle.

int ToAsciiEx(

UINT uVirtKey,	// virtual-key code
UINT ScanCode,	// scan code
BYTE *lpbKeyState,	// address of key-state array
DWORD *lpdwTransKey,	// buffer for translated key
UINT fuState,	// active-menu flag
HKL hkl	// keyboard layout handle
);
Parameters

uVirtKey

Specifies the virtual-key code to be translated.

uScanCode

Specifies the hardware scan code of the key to be translated. The high-order bit of this value is set if the key is up (not pressed).

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

lpdwTransKey

Points to a doubleword buffer that receives the translated Windows character or characters.

fuState

Specifies whether a menu is active. This parameter must be 1 if a menu is active, zero otherwise.

hkl

Identifies the keyboard layout to use to translate the given code. This parameter can be any keyboard layout handle previously returned by the LoadKeyboardLayout function.

Return Value

If the function succeeds, the return value is the number of characters copied to the translated-key buffer. This number is typically greater than one for a ligated key or for an accent and a dead-key character. The function returns a negative value if the specified key is a dead key and returns zero if no conversion was done.

Remarks

The parameters supplied to the ToAsciiEx function might not be sufficient to translate the virtual-key code, because a previous dead key is stored in the keyboard layout.

Typically, ToAsciiEx performs the translation based on the virtual-key code. In some cases, however, bit 15 of the uScanCode parameter may be used to distinguish between a key press and a key release. The scan code is used for translating ALT+number key combinations.

See Also

LoadKeyboardLayout, MapVirtualKeyEx, OemKeyScan, ToAscii, VkKeyScan


ToUnicode

The ToUnicode function translates the specified virtual-key code and keyboard state to the corresponding Unicode character or characters.

int ToUnicode(

UINT  wVirtKey,	// virtual-key code
UINT  wScanCode,	// scan code
PBYTE  lpKeyState,	// address of key-state array
LPWSTR  pwszBuff,	// buffer for translated key
int  cchBuff,	// size of translated key buffer
UINT  wFlags	// set of function-conditioning flags
);
Parameters

wVirtKey

Specifies the virtual-key code to be translated.

wScanCode

Specifies the hardware scan code of the key to be translated. The high-order bit of this value is set if the key is up.

lpKeyState

Points to a 256-byte array that contains the current keyboard state. Each element (byte) in the array contains the state of one key. If the high-order bit of a byte is set, the key is down.

pwszBuff

Points to the buffer that receives the translated Unicode character or characters.

cchBuff

Specifies the size in characters of the buffer pointed to by the pwszBuff parameter.

wFlags

A set of bit flags that condition the behavior of the function. Set bit 0 if a menu is active. Bits 1 through 31 are reserved.

Return Value

The function returns one of the following values:

Value	Meaning
− 1	The specified virtual key is a dead-key character (accent or diacritic). This value is returned regardless of the keyboard layout, even if several characters have been typed and are stored in the keyboard state. If possible, even with Unicode keyboard layouts, the function has written a spacing version of the dead-key character to the buffer specified by pwszBuffer. For example, the function writes the character SPACING ACUTE (0x00B4), rather than the character NON_SPACING ACUTE (0x0301).
0	The specified virtual key has no translation for the current state of the keyboard. Nothing was written to the buffer specified by pwszBuffer.
1	One character was written to the buffer specified by pwszBuffer.
2 or more	Two or more characters were written to the buffer specified by pwszBuff. The most common cause for this is that a dead-key character (accent or diacritic) stored in the keyboard layout could not be combined with the specified virtual key to form a single character.
Remarks

The parameters supplied to the ToUnicode function might not be sufficient to translate the virtual-key code because a previous dead key is stored in the keyboard layout.

Typically, ToUnicode performs the translation based on the virtual-key code. In some cases, however, bit 15 of the wScanCode parameter can be used to distinguish between a key press and a key release.

See Also

ToAscii, VkKeyScan


TrackPopupMenu

The TrackPopupMenu function displays a 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.

BOOL TrackPopupMenu(

HMENU hMenu,	// handle of pop-up menu
UINT uFlags,	// screen-position and mouse-button flags
int x,	// horizontal position, in screen coordinates
int y,	// vertical position, in screen coordinates
int nReserved,	// reserved, must be zero
HWND hWnd,	// handle of owner window
CONST RECT *  *prcRect	// points to RECT that specifies no-dismissal area
);
Parameters

hMenu

Identifies the pop-up menu to be displayed. The handle can be 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.

uFlags

A set of bit flags that specify function options.

Use one of the following bit flag constants to specify how the function positions the popup menu horizontally:

Value	Meaning
TPM_CENTERALIGN	If this flag is set, the function centers the pop-up menu horizontally relative to the coordinate specified by the x parameter.
TPM_LEFTALIGN	If this flag is set, the function 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.
Use one of the following bit flag constants to specify which mouse button the pop-up menu tracks:

Value	Meaning
TPM_LEFTBUTTON	If this flag is set, the pop-up menu tracks the left mouse button.
TPM_RIGHTBUTTON	If this flag is set, the pop-up menu tracks the right mouse button
x

Specifies the horizontal location of the pop-up menu, in screen coordinates.

y

Specifies the vertical location of the pop-up menu, in screen coordinates.

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 function returns.

prcRect

Points to a RECT structure that specifies the portion of the screen 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.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

CreatePopupMenu, GetSubMenu, RECT, WM_COMMAND


TrackPopupMenuEx  (preliminaryWindows 95)
TrackPopupMenuEx  (preliminary−Windows 95)

The TrackPopupMenuEx function displays a 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.

BOOL TrackPopupMenuEx(

HMENU  hmenu,
UINT  fuFlags,
int  x,
int  y,
HWND  hwnd,
LPTPMPARAMS  lptpm
);
Parameters

hmenu

Handle to the pop-up menu to be displayed. This handle can be obtained by calling the CreatePopupMenu function to create a new pop-up menu or by calling the GetSubMenu function to retrieve the handle to a pop-up menu associated with an existing menu item.

fuFlags

Positioning and other options. This parameter, which can be zero or more of the values listed with the TrackPopupMenu function, may also include one of the following values:

Value	Meaning
TPM_HORIZONTAL	If the menu cannot be shown at the specified location without overlapping the excluded rectangle, the system tries to accommodate the requested horizontal alignment before the requested vertical alignment.
TPM_VERTICAL	If the menu cannot be shown at the specified location without overlapping the excluded rectangle, the system tries to accommodate the requested vertical alignment before the requested horizontal alignment.
The excluded rectangle is a portion of the screen that the menu should not overlap; it is specified by lptpm.

x

Horizontal location of the pop-up menu, in screen coordinates.

y

Vertical location of the pop-up menu, in screen coordinates.

hwnd

Handle to 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 function returns.

lptpm

Pointer to a TPMPARAMS structure that specifies an area of the screen the menu should not overlap. This parameter can be NULL.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, use the GetLastError function.

See Also

CreatePopupMenu, GetSubMenu, TPMPARAMS, TrackPopupMenu, WM_COMMAND


TransactNamedPipe

The TransactNamedPipe function combines into a single network operation the functions that write a message to and read a message from the specified named pipe.

BOOL TransactNamedPipe(

HANDLE  hNamedPipe,	// handle of named pipe
LPVOID  lpvWriteBuf,	// address of write buffer
DWORD  cbWriteBuf,	// size of the write buffer, in bytes
LPVOID  lpvReadBuf,	// address of read buffer
DWORD  cbReadBuf,	// size of read buffer, in bytes
LPDWORD  lpcbRead,	// address of variable for bytes actually read
LPOVERLAPPED  lpo	// address of overlapped structure
);
Parameters

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 this parameter 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 by using the CreateEvent function). If the operation cannot be completed immediately, TransactNamedPipe returns FALSE and GetLastError returns ERROR_IO_PENDING. In this situation, the event object is set to the nonsignaled state before TransactNamedPipe returns, and it is set to the signaled state when the transaction has finished.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

TransactNamedPipe fails if the server did not create the pipe as a message-type pipe or if the pipe handle is not in message-read mode. 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 TransactNamedPipe.

The function cannot be completed successfully until data is written into the buffer specified by the lpvReadBuf parameter. 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 the buffer specified by the cbReadBuf parameter, TransactNamedPipe returns FALSE and the GetLastError function returns ERROR_MORE_DATA. The remainder of the message can be read by a subsequent call to ReadFile, ReadFileEx, or PeekNamedPipe.

See Also

CreateEvent, CreateFile, CreateNamedPipe, PeekNamedPipe, ReadFile, ReadFileEx, SetNamedPipeHandleState, OVERLAPPED


TranslateAccelerator

The TranslateAccelerator function processes accelerator keys for menu commands. The function translates a WM_KEYDOWN or WM_SYSKEYDOWN message to a WM_COMMAND or WM_SYSCOMMAND message (if there is an entry for the key in the specified accelerator table) and then sends the WM_COMMAND or WM_SYSCOMMAND message directly to the appropriate window procedure. TranslateAccelerator does not return until the window procedure has processed the message.

int TranslateAccelerator(

HWND  hwnd,	// handle of destination window
HACCEL  haccl,	// handle of accelerator table
LPMSG  lpmsg	// address of structure with message
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

To differentiate the message 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 exist:

•	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 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, MSG, PeekMessage, SetCapture, TranslateMessage, WM_COMMAND, WM_INITMENU, WM_INITMENUPOPUP, WM_KEYDOWN, WM_SYSKEYDOWN, WM_SYSCOMMAND


TranslateCharsetInfo  (preliminaryWindows 95)
TranslateCharsetInfo  (preliminary−Windows 95)

The TranslateCharsetInfo function translates based on the specified character set, code page, or font signature value, setting all members of the destination structure to appropriate values.

UINT TranslateCharsetInfo(lpSrc, lpCs, dwFlags

DWORD FAR * lpSrc,
LPCHARSETINFO lpCs,
DWORD  dwFlags
);
Parameters

lpSrc

Pointer to a character set, code-page, or font signature value. See the dwFlags parameter.

lpCs

Pointer to a CHARSETINFO structure that receives the translated character set information.

dwFlags

Translation flags. This parameter can be one of the following values:

Value	Meaning
TCI_SRCCHARSET	Source contains the character set value in the low word, and zero in the high word.
TCI_SRCCODEPAGE	Source is a code-page value in the low word and zero in the high word.
TCI_SRCFONTSIG	Source is the code-page bitfield portion of a FONTSIGNATURE structure. On input this should have only one Windows code-page bit set, either for an ANSI code-page value or for a common ANSI and OEM value. On output this will have only one bit set. If the TCI_SRCFONTSIG value is given, the lpSrc parameter must be the address of the codepage bit field. If any other TCI_ value is given, the lpSrc parameter must be a value not an address.
See Also

CHARSETINFO, FONTSIGNATURE


TranslateMDISysAccel

The TranslateMDISysAccel function processes accelerator keystrokes for System menu commands of the multiple document interface (MDI) child windows associated with the specified MDI client window. The function translates WM_KEYUP and WM_KEYDOWN messages to WM_SYSCOMMAND messages and sends them to the appropriate MDI child windows.

BOOL TranslateMDISysAccel(

HWND  hwndClient,	// handle of MDI client window
LPMSG  lpmsg	// address of structure with message data
);
Parameters

hwndClient

Identifies the MDI client window.

lpmsg

Points to a message retrieved by using the GetMessage or PeekMessage function. The message must be an MSG structure and contain message information from the application's message queue.

Return Value

If TranslateMDISysAccel translates a message into a system command, the return value is TRUE; otherwise, it is FALSE.

See Also

GetMessage, PeekMessage, TranslateAccelerator, MSG, WM_KEYDOWN, WM_KEYUP, WM_SYSCOMMAND


TranslateMessage

The TranslateMessage function translates virtual-key messages into character messages. The character messages are posted to the calling thread's message queue, to be read the next time the thread calls the GetMessage or PeekMessage function.

BOOL TranslateMessage(

CONST MSG  *lpmsg	// address of structure with message
);
Parameters

lpmsg

Points to an MSG structure that contains message information retrieved from the calling thread's message queue by using the GetMessage or PeekMessage function.

Return Value

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.

Remarks

The TranslateMessage function does not modify the message pointed to by the lpmsg parameter.

WM_KEYDOWN and WM_KEYUP combinations produce a WM_CHAR or WM_DEADCHAR message. WM_SYSKEYDOWN and WM_SYSKEYUP combinations produce a WM_SYSCHAR or WM_SYSDEADCHAR message.

TranslateMessage produces WM_CHAR messages only for keys that are mapped to ASCII characters by the keyboard driver.

If applications process virtual-key messages for some other purpose, they should not call TranslateMessage. For instance, an application should not call TranslateMessage if the TranslateAccelerator function returns TRUE.

See Also

GetMessage, PeekMessage, TranslateAccelerator, WM_CHAR, WM_DEADCHAR, WM_KEYDOWN, WM_KEYUP, WM_SYSCHAR, WM_SYSDEADCHAR, WM_SYSKEYDOWN, WM_SYSKEYUP


TransmitCommChar

The TransmitCommChar function transmits a specified character ahead of any pending data in the output buffer of the specified communications device.

BOOL TransmitCommChar(

HANDLE  hCommDev,	// handle of communications device
char  chTransmit	// character to transmit
);
Parameters

hCommDev

Identifies the communications device. The CreateFile function returns this handle.

chTransmit

Specifies the character to be transmitted.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The TransmitCommChar function is useful for sending an interrupt character (such as a CTRL+C) to a host system.

If the device is not transmitting, TransmitCommChar cannot be called repeatedly. Once TransmitCommChar places a character in the output buffer, the character must be transmitted before the function can be called again. If the previous character has not yet been sent, TransmitCommChar returns an error.

Character transmission is subject to normal flow control and handshaking. This function can only be called synchronously.

See Also

CreateFile, WaitCommEvent


TransmitFile  (preliminaryWindows NT)
TransmitFile  (preliminary−Windows NT)

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

BOOL TransmitFile(

HWND  hSocket,	// handle to a connected socket
HWND  hFile,	// handle to an open file
HWND  nNumberOfBytesToWrite,	// number of bytes to transmit
HWND  nNumberOfBytesPerSend,	// number of bytes per sockets send operation
HWND  lpOverlapped,	// pointer to overlapped I/O data structure
HWND  lpTransmitBuffers	// pointer to data to send before and after file data
);
Parameters

hSocket

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

The socket specified by hSocket must be a virtual circuit socket. A socket of type SOCK_STREAM, SOCK_SEQPACKET, or SOCK_RDM is a virtual circuit socket. The TransmitFile function does not support datagram sockets.

hFile

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

nNumberOfBytesToWrite

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

Set this parameter to zero to transmit the entire file, s.

nNumberOfBytesPerSend

Specifies the size of each sockets send operation. This specification is for use by the sockets layer of the operating system.

Set this parameter to zero to indicate that the sockets layer should use an intelligent default send size.

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

lpOverlapped

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

Note that, by default, socket handles are opened as overlapped.

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

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

lpTransmitBuffers

Pointer to a TRANSMIT_FILE_BUFFERS data structure that contains pointers to data to send before and after the file data is sent.

Set this parameter to NULL if you only want to transmit the file data.

Return Value

If the function succeeds, the return value is TRUE.

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

Note that the function returns FALSE if an overlapped I/O operation is not complete before TransmitFile returns. In that case, GetLastError returns ERROR_IO_PENDING.

See Also

OVERLAPPED, TRANSMIT_FILE_BUFFERS


UInt32x32To64

For further information see UInt32x32To64 in the Win32 (part 2) help file.

The UInt32x32To64 function multiplies two unsigned 32-bit integers, returning an unsigned 64-bit integer result. The function performs optimally on all Win32 platforms.

DWORDLONG UInt32x32To64(

DWORD  Multiplier,	// specifies first unsigned 32-bit integer for the multiplication
DWORD  Multiplicand	// specifies second unsigned 32-bit integer for the multiplication
);
Parameters

Multiplier

Specifies the first unsigned 32-bit integer for the multiplication.

Multiplicand

Specifies the second unsigned 32-bit integer for the multiplication.

Return Value

The return value is the unsigned 64-bit integer result of the multiplication.

Remarks

This function is implemented on all platforms by optimal inline code: a single multiply instruction that returns a 64-bit result.

Please note that the function's return value is a 64-bit value, not a LARGE_INTEGER structure.

See Also

Int32x32To64


UndeleteFile

The UndeleteFile function is an application-defined callback function that File Manager calls when the user chooses the Undelete command from the File Manager File menu.

DWORD APIENTRY UndeleteFile(

HWND  hwndOwner,	// handle of File Manager window
LPSTR  lpszDir	// address of name of initial directory
);
Parameters

hwndOwner

Identifies the File Manager window. An "undelete" dynamic-link library (DLL) should use this handle to specify the owner window for any dialog box or message box the DLL may display.

lpszDir

Points to a null-terminated string that contains the name of the initial directory.

Return Value

If the function succeeds, the return value is one of the following:

Value	Meaning
−l	An error occurred.
IDOK	A file was undeleted. File Manager repaints its windows.
IDCANCEL	No file was undeleted.


UnhandledExceptionFilter

The UnhandledExceptionFilter function passes unhandled exceptions to the debugger, if the process is being debugged. Otherwise, it optionally displays an Application Error message box and causes the exception handler to be executed. This function can be called only from within the filter expression of a try-except exception handler.

LONG UnhandledExceptionFilter(

STRUCT _EXCEPTION_POINTERS *  lpexpExceptionInfo	// address of exception info
);
Parameters

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.

Return Value

The function returns one of the following values:

Value	Meaning
EXCEPTION_CONTINUE_SEARCH	The process is being debugged, so the exception should be passed (as second chance) to the application's debugger.
EXCEPTION_EXECUTE_HANDLER	If the SEM_NOGPFAULTERRORBOX flag was specified in a previous call to SetErrorMode, no Application Error message box is displayed. The function returns control to the exception handler, which is free to take any appropriate action.
Remarks

If the process is not being debugged, the function displays an Application Error message box, depending on the current error mode. The default behavior is to display the dialog box, but this can be disabled by specifying SEM_NOGPFAULTERRORBOX in a call to the SetErrorMode function.

The system uses UnhandledExceptionFilter internally to handle exceptions that occur during process and thread creation.

See Also

EXCEPTION_POINTERS, GetExceptionInformation, SetErrorMode, SetUnhandledExceptionFilter, UnhandledExceptionFilter


UnhookWindowsHook

The UnhookWindowsHook function is obsolete, but is provided for compatibility with 16-bit versions of Windows. For Win32-based applications, use the UnhookWindowsHookEx function.

BOOL UnhookWindowsHook(

int  nCode,	// type of hook to remove procedure from
HOOKPROC  hkprc	// address of hook procedure
);


UnhookWindowsHookEx

The UnhookWindowsHookEx function removes a hook procedure installed in a hook chain by the SetWindowsHookEx function.

BOOL UnhookWindowsHookEx(

HHOOK  hhook	// handle of hook procedure to remove
);
Parameters

hhook

Identifies the hook to be removed. This parameter is a hook handle obtained by a previous call to SetWindowsHookEx.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The hook procedure can be in the state of being called by another thread even after UnhookWindowsHookEx returns. If the hook procedure is not being called concurrently, the hook procedure is removed immediately before UnhookWindowsHookEx returns.

See Also

SetWindowsHookEx, UnhookWindowsHook


UnionRect

The UnionRect function creates the union of two rectangles. The union is the smallest rectangle that contains both source rectangles.

BOOL UnionRect(

LPRECT  lprcDst,	// address of structure for union
CONST RECT  *lprcSrc1,	// address of structure with first rectangle
CONST RECT  *lprcSrc2	// address of structure with second rectangle
);
Parameters

lprcDst

Points to the RECT structure that will receive a rectangle containing the rectangles pointed to by the lprcSrc1 and lprcSrc2 parameters.

lprcSrc1

Points to the RECT structure that contains the first source rectangle.

lprcSrc2

Points to the RECT structure that contains the second source rectangle.

Return Value

If the specified structure contains a nonempty rectangle, the return value is TRUE; otherwise, it is FALSE. To get extended error information, call GetLastError.

Remarks

Windows ignores the dimensions of an empty rectangle — that is, a rectangle in which all coordinates are set to zero, so that it has no height or no width.

See Also

InflateRect, IntersectRect, OffsetRect, RECT


UnloadKeyboardLayout

The UnloadKeyboardLayout function removes a keyboard layout.

BOOL UnloadKeyboardLayout(

HKL  hkl	// handle of keyboard layout
);
Parameters

hkl

Identifies the keyboard layout to unload.

Return Value

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

ActivateKeyboardLayout, GetKeyboardLayoutName, LoadKeyboardLayout


UnlockFile

The UnlockFile function unlocks a region in an open file. Unlocking a region enables other processes to access the region.

BOOL UnlockFile(

HANDLE  hFile,	// handle of file to unlock
DWORD  dwFileOffsetLow,	// low-order word of lock region offset
DWORD  dwFileOffsetHigh,	// high-order word of lock region offset
DWORD  cbUnlockLow,	// low-order word of length to unlock
DWORD  cbUnlockHigh	// high-order word of length to unlock
);
Parameters

hFile

Identifies a file that contains a region locked with LockFile. The file handle must have been created with either GENERIC_READ or GENERIC_WRITE access to the file.

dwFileOffsetLow

Specifies the low-order word of the starting byte offset in the file where the locked region begins.

dwFileOffsetHigh

Specifies the high-order word of the starting byte offset in the file where the locked region begins.

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Unlocking a region of a file releases a lock on the file. The region to unlock must correspond exactly to an existing locked region. For example, two adjacent regions of a file cannot be locked separately and then unlocked as a single region that spans both locked regions.

A process should not be terminated with a portion of a file locked and a file that has locked regions should not be closed.

This function works on a file allocation table (FAT) − based file system only if the operating system is running SHARE.EXE.

See Also

CreateFile, LockFile


UnlockFileEx

The UnlockFileEx function unlocks a previously locked byte range in an open file.

BOOL UnlockFileEx(

HANDLE  hFile,	// handle of file to unlock
DWORD  dwReserved,	// reserved, must be set to zero
DWORD  nNumberOfBytesToUnlockLow,	// low order 32-bits of length to unlock
DWORD  nNumberOfBytesToUnlockHigh,	// high order 32-bits of length to unlock
LPOVERLAPPED  lpOverlapped	// addr. of struct. with unlock region start offset
);
Parameters

hFile

Identifies an open handle to a file that is to have an existing locked region unlocked. The handle must have been created with either GENERIC_READ or GENERIC_WRITE access to the file.

dwReserved

Reserved parameter; must be zero.

nNumberOfBytesToUnlockLow

Specifies the low-order 32-bits of the length of the byte range to unlock.

nNumberOfBytesToUnlockHigh

Specifies the high-order 32-bits of the length of the byte range to unlock.

lpOverlapped

Points to an OVERLAPPED structure that the function uses with the unlocking request. This structure contains the file offset of the beginning of the unlock range.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Unlocking a region of a file releases a previously acquired lock on a file. The region to unlock must correspond exactly to an existing locked region. Two adjacent regions of a file can not be locked separately and then unlocked using a single region that spans both locked regions.

If a process terminates with a portion of a file locked or closes a file that has outstanding locks, the behavior is not specified.

See Also

CreateFile, LockFile, LockFileEx, OVERLAPPED, UnlockFile


UnlockResource

The UnlockResource function is obsolete. It is not necessary for Win32-based applications to unlock resources.

See Also

LoadResource, LockResource


UnlockSegment

The UnlockSegment function is obsolete. Segments have no meaning in the 32-bit environment.


UnlockServiceDatabase

The UnlockServiceDatabase function unlocks a service control manager database by releasing the specified lock.

BOOL UnlockServiceDatabase(

SC_LOCK  sclLock	// service control manager database lock to be released
);
Parameters

sclLock

Specifies a lock obtained from a previous call to the LockServiceDatabase function.

Return Value

If the function succeeds, the return value is TRUE.

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

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.

Value	Meaning
ERROR_INVALID_SERVICE_LOCK	The specified lock is invalid.
See Also

LockServiceDatabase, QueryServiceLockStatus


UnmapViewOfFile

The UnmapViewOfFile function unmaps a mapped view of a file from the calling process's address space.

BOOL UnmapViewOfFile(

LPVOID  lpBaseAddress	// address where mapped view begins
);
Parameters

lpBaseAddress

Points to the base address of the mapped view of a file that is to be unmapped. This value must be identical to the value returned by a previous call to the MapViewOfFile or MapViewOfFileEx function.

Return Value

If the function succeeds, the return value is TRUE, and all dirty pages within the specified range are written "lazily" to disk.

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

See Also

MapViewOfFile, MapViewOfFileEx


UnpackDDElParam

The UnpackDDElParam function unpacks a DDE lParam value received from a posted DDE message.

BOOL UnpackDDElParam(

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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

PackDDElParam eases the porting of 16-bit DDE applications to 32-bit DDE applications.

See Also

FreeDDElParam, PackDDElParam, ReuseDDElParam


UnrealizeObject

The UnrealizeObject function resets a logical palette. It directs the system to realize the palette as though it had not previously been realized. The next time the application calls the RealizePalette function for the specified palette, the system completely remaps the logical palette to the system palette.

If hgdiobj is a brush, UnrealizeObject does nothing, and the function returns TRUE. Use SetBrushOrgEx to set the origin of a brush.

BOOL UnrealizeObject(

HGDIOBJ  hgdiobj	// logical palette handle
);
Parameters

hgdiobj

Identifies the logical palette to be reset.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The UnrealizeObject function should not be used with stock objects. The default palette, obtained by calling GetStockObject(DEFAULT_PALETTE), is a stock object.

A palette identified by hgdiobj can be the currently selected palette of a device context.

See Also

GetStockObject, RealizePalette, SetBrushOrgEx


UnregisterClass

The UnregisterClass function removes a window class, freeing the memory required for the class.

BOOL UnregisterClass(

LPCTSTR  lpszClass,	// address of class name string
HINSTANCE  hinst	// handle of application instance
);
Parameters

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.

If lpszClass is a string, it specifies the window class name. This class name must have been registered by a previous call to the RegisterClass function. System global classes, such as dialog box controls, cannot be unregistered.

hinst

Identifies the instance of the module that created the class.

Return Value

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, call GetLastError.

Remarks

Before calling this function, an application must destroy all windows created with the specified class.

All window classes that an application registers are unregistered when it terminates.

See Also

GlobalAddAtom, RegisterClass


UnregisterHotKey

The UnregisterHotKey function frees a hot key previously registered by the calling thread.

BOOL UnregisterHotKey(

HWND  hwnd,	// window associated with hot key
int  idHotKey	// identifier of hot key
);
Parameters

hwnd

Identifies the window associated with the hot key to be freed. This parameter should be NULL if the hot key is not associated with a window.

idHotKey

Specifies the identifier of the hot key to be freed.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

RegisterHotKey, WM_HOTKEY


UpdateColors

The UpdateColors function updates the client area of the specified device context by remapping the current colors in the client area to the currently realized logical palette.

BOOL UpdateColors(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies the device context.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application can determine whether a device supports palette operations by calling the GetDeviceCaps function and specifying the RASTERCAPS constant.

An inactive window with a realized logical palette may call UpdateColors as an alternative to redrawing its client area when the system palette changes.

The UpdateColors function typically updates a client area faster than redrawing the area. However, because UpdateColors performs the color translation based on the color of each pixel before the system palette changed, each call to this function results in the loss of some color accuracy.

This function must be called soon after a WM_PALETTECHANGED message is received.

See Also

GetDeviceCaps, RealizePalette


UpdateResource

The UpdateResource function adds, deletes, or replaces a resource in an executable file.

BOOL UpdateResource(

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
);
Parameters

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.

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

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, in bytes, of the resource data at lpvData.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

An application can use UpdateResource repeatedly to make changes to the resource data. Each call to UpdateResource contributes to an internal list of additions, deletions, and replacements but does not actually write the data to the executable file. The application must use the EndUpdateResource function to write the accumulated changes to the executable file.

See Also

BeginUpdateResource, EndUpdateResource, LoadIcon, LoadString, LockResource, MAKEINTRESOURCE, MAKELANGID, SizeofResource


UpdateWindow

The UpdateWindow function updates the client area of the specified window by sending a WM_PAINT message to the window if the window's update region is not empty. The function sends a WM_PAINT message directly to the window procedure of the specified window, bypassing the application queue. If the update region is empty, no message is sent.

BOOL UpdateWindow(

HWND  hwnd	// handle of window
);
Parameters

hwnd

Identifies the window to be updated.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

See Also

ExcludeUpdateRgn, GetUpdateRect, GetUpdateRgn, InvalidateRect, InvalidateRgn, WM_PAINT


ValidateRect

The ValidateRect function validates the client area within a rectangle by removing the rectangle from the update region of the specified window.

BOOL ValidateRect(

HWND  hwnd,	// handle of window
CONST RECT  *lprc	// address of validation rectangle coordinates
);
Parameters

hwnd

Identifies the window whose update region is to be modified. If this parameter is NULL, Windows invalidates and redraws all windows and sends the WM_ERASEBKGND and WM_NCPAINT messages to the window procedure before the function returns.

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.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The BeginPaint function automatically validates the entire client area. Neither the ValidateRect nor ValidateRgn function should be called if a portion of the update region must be validated before the next WM_PAINT message is generated.

Windows continues to generate WM_PAINT messages until the current update region is validated.

See Also

BeginPaint, InvalidateRect, InvalidateRgn, RECT, ValidateRgn, WM_PAINT


ValidateRgn

The ValidateRgn function validates the client area within a region by removing the region from the current update region of the specified window.

BOOL ValidateRgn(

HWND  hwnd,	// handle of window
HRGN  hrgn	// handle of valid region
);
Parameters

hwnd

Identifies the window whose update region is to be modified.

hrgn

Identifies a region that defines the area to be removed from the update region. If this parameter is NULL, the entire client area is removed.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The specified region must have been created by a region function. The region coordinates are assumed to be client coordinates.

The BeginPaint function automatically validates the entire client area. Neither the ValidateRect nor ValidateRgn function should be called if a portion of the update region must be validated before the next WM_PAINT message is generated.

See Also

BeginPaint, ExcludeUpdateRgn, InvalidateRect, InvalidateRgn, ValidateRect, WM_PAINT


VerFindFile

The VerFindFile function determines where to install a file based on whether it locates another version of the file in the system. The values VerFindFile returns in the specified buffers are used in a subsequent call to VerInstallFile.

As with the other file installation functions, VerFindFile will only work with Win32 file images. 16-bit Windows file images are not supported.

DWORD VerFindFile(

DWORD  dwFlags,	// bit flags that condition function behavior
LPTSTR  szFileName,	// file to be installed
LPTSTR  szWinDir,	// Windows directory
LPTSTR  szAppDir,	// directory where related files are being installed
LPTSTR  szCurDir,	// receives path of directory where file is currently installed
PUINT  lpuCurDirLen,	// size of string in szCurDir
LPTSTR  szDestDir,	// receives path of recommended destination directory
PUINT  lpuDestDirLen	// size of string in szDestDir
);
Parameters

dwFlags

Contains a bitmask of flags. This parameter can be the following value:

Flag	Description
VFFF_ISSHAREDFILE	The source file can be shared by multiple applications. An application can use this information to determine where the file should be copied.
All other values are reserved.

szFileName

Points to the name of the file to be installed. The filename can include only the filename and extension, not a path.

szWinDir

Points to the directory in which Windows is running or will be run. This string is returned by the GetWindowsDirectory function.

szAppDir

Points to the directory where the installation program is installing a set of related files. If the installation program is installing an application, this is the directory where the application will reside. This parameter also points to the application's current directory unless otherwise specified.

szCurDir

Points to a buffer that receives the path to a current version of the file being installed. The path is a zero-terminated string. If a current version is not installed, the buffer will contain a zero-length string. The buffer should be at least _MAX_PATH characters long, although this is not required.

lpuCurDirLen

Points to a variable that contains the length of the szCurDir buffer. This pointer must not be NULL.

When the function returns, lpuCurDirLen contains the size, in characters, of the data returned in szCurDir, including the terminating null character. If the buffer is too small to contain all the data, lpuCurDirLen will be the size of the buffer required to hold the path.

szDestDir

Points to a buffer that receives the path to the installation location recommended by VerFindFile. The path is a zero-terminated string. The buffer should be at least _MAX_PATH characters long, although this is not required.

lpuDestDirLen

Points to a variable that contains the length of the szDestDir buffer. This pointer must not be NULL.

When the function returns, lpuDestDirLen contains the size, in characters, of the data returned in szDestDir, including the terminating null character. If the buffer is too small to contain all the data, lpuDestDirLen will be the size of the buffer needed to hold the path.

Return Value

The return value is a bitmask that indicates the status of the file. It can be one or more of the following values:

Value	Meaning
VFF_CURNEDEST	The currently installed version of the file is not in the recommended destination.
VFF_FILEINUSE	Windows is using the currently installed version of the file; therefore, the file cannot be overwritten or deleted.
VFF_BUFFTOOSMALL	At least one of the buffers was too small to contain the corresponding string. An application should check the output buffers to determine which buffer was too small.
All other values are reserved.

Remarks

VerFindFile searches for a copy of the specified file by using the OpenFile function. However, it determines the system directory from the specified Windows directory, or searches the path.

If the dwFlags parameter indicates that the file is private to this application (not VFFF_ISSHAREDFILE), VerFindFile recommends installing the file in the application's directory. Otherwise, if the system is running a shared copy of Windows, the function recommends installing the file in the Windows directory. If the system is running a private copy of Windows, the function recommends installing the file in the system directory.

See Also

GetWindowsDirectory, OpenFile, VerInstallFile


VerInstallFile

The VerInstallFile function attempts to install the specified file based on information returned from the VerFindFile function. VerInstallFile decompresses the file, if necessary, assigns a unique filename, and checks for errors, such as outdated files.

As with the other file installation functions, VerInstallFile will only work with Win32 file images. 16-bit Windows file images are not supported.

DWORD VerInstallFile(

DWORD  dwFlags,	// bit flags that condition function behavior
LPTSTR  szSrcFileName,	// file to install
LPTSTR  szDestFileName,	// new name of file to install
LPTSTR  szSrcDir,	// source directory of file to install
LPTSTR  szDestDir,	// directory in which to install file
LPTSTR  szCurDir,	// directory where file is currently installed
LPTSTR  szTmpFile,	// receives name of temporary copy of file used during installation
PUINT  lpuTmpFileLen	// size of string in szTmpFile
);
Parameters

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.

szSrcFileName

Points to the name of the file to be installed. This is the filename in the directory pointed to by the szSrcDir parameter; the filename can include only the filename and extension, not a path.

szDestFileName

Points to the name VerInstallFile will give the new file upon installation. This filename may be different from the filename in the szSrcFileName directory. The new name should include only the filename and extension, not a path.

szSrcDir

Points to a buffer that contains the name of the directory where the new file is found.

szDestDir

Points to a buffer that contains the name of the directory where the new file should be installed. VerFindFile returns this value in its szDestDir parameter.

szCurDir

Points to a buffer that contains the name of the directory where the preexisting version of this file is found. VerFindFile returns this value in its szCurDir parameter.

szTmpFile

Points to a buffer that should be empty upon the initial call to VerInstallFile. The function fills the buffer with the name of a temporary copy of the source file. The buffer should be at least _MAX_PATH characters long, although this is not required.

lpuTmpFileLen

Points to a variable that contains the length of the szTmpFile buffer. This pointer must not be NULL.

When the function returns, lpuTmpFileLen contains the size, in characters, of the data returned in szTmpFile, including the terminating null character. If the buffer is too small to contain all the data, lpuTmpFileLen will be the size of the buffer required to hold the data.

Return Value

The return value is a bitmask that indicates exceptions. It can be one or more of the following values:

Value	Meaning
VIF_TEMPFILE	The temporary copy of the new file is in the destination directory. The cause of failure is reflected in other flags.
VIF_MISMATCH	The new and preexisting files differ in one or more attributes. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag set.
VIF_SRCOLD	The file to install is older than the preexisting file. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag set.
VIF_DIFFLANG	The new and preexisting files have different language or code-page values. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag set.
VIF_DIFFCODEPG	The new file requires a code page that cannot be displayed by the version of Windows currently running. This error can be overridden by calling VerInstallFile with the VIFF_FORCEINSTALL flag set.
VIF_DIFFTYPE	The new file has a different type, subtype, or operating system from the preexisting file. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag set.
VIF_WRITEPROT	The preexisting file is write protected. This error can be overridden by calling VerInstallFile again with the VIFF_FORCEINSTALL flag set.
VIF_FILEINUSE	The preexisting file is in use by Windows and cannot be deleted.
VIF_OUTOFSPACE	The function cannot create the temporary file due to insufficient disk space on the destination drive.
VIF_ACCESSVIOLATION	A read, create, delete, or rename operation failed due to an access violation.
VIF_SHARINGVIOLATION	A read, create, delete, or rename operation failed due to a sharing violation.
VIF_CANNOTCREATE	The function cannot create the temporary file. The specific error may be described by another flag.
VIF_CANNOTDELETE	The function cannot delete the destination file, or cannot delete the existing version of the file located in another directory. If the VIF_TEMPFILE bit is set, the installation failed, and the destination file probably cannot be deleted.
VIF_CANNOTDELETECUR	The existing version of the file could not be deleted and VIFF_DONTDELETEOLD was not specified.
VIF_CANNOTRENAME	The function cannot rename the temporary file, but already deleted the destination file.
VIF_OUTOFMEMORY	The function cannot complete the requested operation due to insufficient memory. Generally, this means the application ran out of memory attempting to expand a compressed file.
VIF_CANNOTREADSRC	The function cannot read the source file. This could mean that the path was not specified properly.
VIF_CANNOTREADDST	The function cannot read the destination (existing) files. This prevents the function from examining the file's attributes.
VIF_BUFFTOOSMALL	The szTmpFile buffer was too small to contain the name of the temporary source file. When the function returns, lpuTmpFileLen contains the size of the buffer required to hold the filename.
All other values are reserved.

Remarks

VerInstallFile copies the file from the source directory to the destination directory. If szCurDir indicates that a previous version of the file exists on the system, VerInstallFile compares the files' version stamp information. If the previously installed version of the file is more recent than the new version, or if the files' attributes are significantly different, for example, if they are in different languages, then VerInstallFile returns with one or more recoverable error codes.

VerInstallFile leaves the temporary file in the destination directory. The application can either override the error or delete the temporary file. If the application overrides the error, VerInstallFile deletes the previously installed version and renames the temporary file with the original filename.

See Also

VerFindFile


VerLanguageName

The VerLanguageName function converts the specified binary Microsoft language identifier into a text representation of the language.

DWORD VerLanguageName(

DWORD  idLang,	// Microsoft language identifier
LPTSTR  lpszLang,	// address of buffer for language string
DWORD  cbLang	// size of buffer
);
Parameters

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 Win32, see the following Remarks 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.

Return Value

If the return value is less than or equal to the buffer size, the return value is the size, in characters, of the string returned in the buffer. This value does not include the terminating null character.

If the return value is greater than the buffer size, the return value is the size of the buffer required to hold the entire string. The string is truncated to the length of the existing buffer.

If an error occurs, the return value is zero. Unknown language identifiers do not produce errors.

Remarks

Typically, an installation program uses this function to translate a language identifier returned by the VerQueryValue function. The text string may be used in a dialog box that asks the user how to proceed in the event of a language conflict.

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

VerQueryValue


VerQueryValue

The VerQueryValue function returns selected version information from the specified version-information resource. To retrieve the appropriate resource, the GetFileVersionInfo function must be called before VerQueryValue.

As with the other file installation functions, VerQueryValue will only work with Win32 file images. 16-bit Windows file images are not supported.

BOOL VerQueryValue(

const LPVOID  pBlock,	// address of buffer for version resource
LPTSTR  lpSubBlock,	// address of value to retrieve
LPVOID  *lplpBuffer,	// address of buffer for version pointer
PUINT  puLen	// address of version-value length buffer
);
Parameters

pBlock

Points to the buffer containing the version-information resource returned by GetFileVersionInfo.

lpSubBlock

Points to a zero-terminated string specifying which version-information value to retrieve. The string consists of names separated by backslashes (\) and can have one of the following forms:

Form	Description
\	Specifies the root block. The function retrieves a pointer to the VS_FIXEDFILEINFO structure for the version-information resource.
\VarFileInfo\Translation	Specifies the translation table in the variable information structure. The function retrieves a pointer to an array of language and character-set identifiers. An application uses these identifiers to create the name of a language-specific structure in the version-information resource.
\StringFileInfo\lang-charset\string-name	Specifies a value in a language-specific structure. The lang-charset name is a concatenation of a language and character-set identifier pair found in the translation table for the resource. The lang-charset name must be specified as a hexadecimal string. The string-name name is one of the predefined strings described in the following Remarks section.
lplpBuffer

Points to a buffer that receives a pointer to the version-information value.

puLen

Points to a buffer that receives the length, in characters, of the version-information value.

Return Value

If the specified structure exists and version information is available, the return value is nonzero. If the address of the length buffer is zero, no value is available for the specified version-information name. If the specified name does not exist or the specified resource is not valid, the return value is zero.

Remarks

The Win32 API contains the following predefined version information strings:

CompanyName FileDescription FileVersion InternalName LegalCopyright OriginalFilename ProductName ProductVersion

The following example shows how to retrieve the FileDescription string-value from a block of version information:

VerQueryValue(pBlock,

              TEXT("\\StringFileInfo\\040904E4\\FileDescription"),

              &lpBuffer,

              &dwBytes);

Call the GetFileVersionInfoSize and GetFileVersionInfo functions to properly initialize the pBlock buffer before calling the VerQueryValue function.

See Also

GetFileVersionInfo, GetFileVersionInfoSize, VS_FIXEDFILEINFO, VS_VERSION_INFO


VirtualAlloc

The VirtualAlloc function reserves or commits a region of pages in the virtual address space of the calling process. Memory allocated by this function is automatically initialized to zero.

LPVOID VirtualAlloc(

LPVOID  lpvAddress,	// address of region to reserve or commit
DWORD  cbSize,	// size of region
DWORD  fdwAllocationType,	// type of allocation
DWORD  fdwProtect	// type of access protection
);
Parameters

lpvAddress

Specifies the desired starting address of the region to allocate. If the memory is being reserved, the specified address is rounded down to the next 64-kilobyte boundary. If the memory is already reserved and is being committed, the address is rounded down to the next page boundary. To determine the size of a page on the host computer, use the GetSystemInfo function. If this parameter is NULL, the system determines where to allocate the region.

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. You can specify any combination of the following flags:

Flag	Meaning
MEM_COMMIT	Allocates physical storage in memory or in the paging file on disk for the specified region of pages.
	An attempt to commit an already committed page will not cause the function to fail. This means that a range of committed or decommitted pages can be committed without having to worry about a failure.
MEM_RESERVE	Reserves a range of the process's virtual address space without allocating any physical storage. The reserved range cannot be used by any other allocation operations (the malloc function, the LocalAlloc function, and so on) until it is released. Reserved pages can be committed in subsequent calls to the VirtualAlloc function.
MEM_TOP_DOWN	Allocates memory at the highest possible address.
fdwProtect

Specifies the type of access protection. If the pages are being committed, any one of the following flags can be specified, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as desired:

Flag	Meaning
PAGE_READONLY	Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE	Enables both read and write access to the committed region of pages.
PAGE_EXECUTE	Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ	Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE	Enables execute, read, and write access to the committed region of pages.
PAGE_GUARD	Pages in the region become guard pages. Any attempt to read from or write to a guard page causes the operating system to raise a STATUS_GUARD_PAGE exception and turn off the guard page status. Guard pages thus act as a one-shot access alarm. The PAGE_GUARD flag is a page protection modifier. An application uses it with one of the other page protection flags, with one exception: It cannot be used with PAGE_NOACCESS. When an access attempt leads the operating system to turn off guard page status, the underlying page protection takes over. If a guard page exception occurs during a system service, the service typically returns a failure status indicator.
PAGE_NOACCESS	Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE	Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be specified as "no cache." This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
Return Value

If the function succeeds, the return value is the base address of the allocated region of pages.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

VirtualAlloc can perform the following operations:

•	Commit a region of pages reserved by a previous call to the VirtualAlloc function.

•	Reserve a region of free pages.

•	Reserve and commit a region of free pages.

You can use VirtualAlloc to reserve a block of pages and then make additional calls to VirtualAlloc to commit individual pages from the reserved block. This enables a process to reserve a range of its virtual address space without consuming physical storage until it is needed.

Each page in the process's virtual address space is in one of three states:

State	Meaning
Free	The page is not committed or reserved and is not accessible to the process. VirtualAlloc can reserve, or simultaneously reserve and commit, a free page.
Reserved	The range of addresses cannot be used by other allocation functions, but the page is not accessible and has no physical storage associated with it. VirtualAlloc can commit a reserved page, but it cannot reserve it a second time. The VirtualFree function can release a reserved page, making it a free page.
Committed	Physical storage is allocated for the page, and access is controlled by a protection code. The system initializes and loads each committed page into physical memory only at the first attempt to read or write to that page. When the process terminates, the system releases the storage for committed pages. VirtualAlloc can commit an already committed page. This means that you can commit a range of pages, regardless of whether they have already been committed, and the function will not fail. VirtualFree can decommit a committed page, releasing the page's storage, or it can simultaneously decommit and release a committed page.
If the 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 preceding list.

The PAGE_GUARD protection modifier flag establishes guard pages. Guard pages act as one-shot access alarms.

See Also

GlobalAlloc, HeapAlloc, VirtualFree, VirtualLock, VirtualProtect, VirtualQuery


VirtualFree

The VirtualFree function releases or decommits (or both) a region of pages within the virtual address space of the calling process.

BOOL VirtualFree(

LPVOID  lpvAddress,	// address of region of committed pages
DWORD  cbSize,	// size of region
DWORD  fdwFreeType	// type of free operation
);
Parameters

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. One, but not both, of the following flags can be specified:

Flag	Meaning
MEM_DECOMMIT	Decommits the specified region of committed pages.
	An attempt to decommit an uncommitted page will not cause the function to fail. This means that a range of committed or uncommitted pages can be decommitted without having to worry about a failure.
MEM_RELEASE	Releases the specified region of reserved pages. If this flag is specified, the cbSize parameter must be zero, or the function fails.
Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

VirtualFree can perform one of the following operations:

•	Decommit a region of committed or uncommitted pages.

•	Release a region of reserved pages.

•	Decommit and release a region of committed or uncommitted pages.

To release a region of pages, the entire range of pages must be in the same state (all reserved or all committed) and the entire region originally reserved by the VirtualAlloc function must be released at the same time. If only part of the pages in the original reserved region are committed, you must first call VirtualFree to decommit the committed pages and then call VirtualFree again to release the entire block.

Pages that have been released are free pages available for subsequent allocation operations. Attempting to read from or write to a free page results in an access violation exception.

VirtualFree can decommit an uncommitted page; this means that a range of committed or uncommitted pages can be decommitted without having to worry about a failure. Decommitting a page releases its physical storage, either in memory or in the paging file on disk. If a page is decommitted but not released, its state changes to reserved, and it can be committed again by a subsequent call to VirtualAlloc. Attempting to read from or write to a reserved page results in an access violation exception.

The current state of the entire range of pages must be compatible with the type of free operation specified by the fdwFreeType parameter. Otherwise, the function fails and no pages are released or decommitted.

See Also

GlobalAlloc, GlobalFree, VirtualAlloc


VirtualLock

The VirtualLock function locks the specified region of the process's virtual address space into memory, ensuring that subsequent access to the region will not incur a page fault.

BOOL VirtualLock(

LPVOID  lpvAddress,	// address of first byte of range to lock
DWORD  cbSize	// number of bytes in range to lock
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

All pages in the specified region must be committed. Memory protected with the PAGE_NOACCESS flag cannot be locked.

Locking pages into memory may degrade the performance of the system by reducing the available RAM and forcing the system to swap out other critical pages to the paging file. By default, a process can lock a maximum of 30 pages. The default limit is intentionally small to avoid severe performance degradation. Applications that need to lock larger numbers of pages must first call the SetProcessWorkingSetSize function to increase their minimum and maximum working set sizes. The maximum number of pages that a process can lock is equal to the number of pages in its minimum working set minus a small overhead.

Pages that a process has locked remain resident even when the process is idle for extended periods.

To unlock a region of locked pages, use the VirtualUnlock function. Locked pages are automatically unlocked when the process terminates.

This function is not like the GlobalLock or LocalLock function in that it does not increment a lock count and translate a handle into a pointer. There is no lock count for virtual pages, so multiple calls to the VirtualUnlock function are never required to unlock a region of pages.

Windows 95

On Windows 95, the VirtualLock function is implemented as a stub that has no effect and always returns TRUE.

See Also

GlobalLock, LocalLock, SetProcessWorkingSetSize, VirtualUnlock


VirtualProtect

The VirtualProtect function changes the access protection on a region of committed pages in the virtual address space of the calling process. This function differs from VirtualProtectEx, which changes the access protection of any process.

BOOL VirtualProtect(

LPVOID  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
);
Parameters

lpvAddress

Points to the base address of the region of pages whose access protection attributes are to be changed.

cbSize

Specifies the size, in bytes, of the region whose access protection attributes are to be changed. The region of affected pages includes all pages containing one or more bytes in the range from the 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. You can specify any one of the following flags, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags, as necessary:

Value	Meaning
PAGE_READONLY	Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE	Enables both read and write access to the committed region of pages.
PAGE_WRITECOPY	Gives copy-on-write access to the committed region of pages.
PAGE_EXECUTE	Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ	Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE	Enables execute, read, and write access to the committed region of pages.
PAGE_EXECUTE_WRITECOPY	Enables execute, read, and write access to the committed region of pages. The pages are shared read-on-write and copy-on-write.
PAGE_GUARD	Pages in the region become guard pages. Any attempt to access a guard page causes the operating system to raise a STATUS_GUARD_PAGE exception and turn off the guard page status. Guard pages thus act as a one-shot access alarm. The PAGE_GUARD flag is a page protection modifier. An application uses it with one of the other page protection flags, with one exception: it cannot be used with PAGE_NOACCESS. When an access attempt leads the operating system to turn off guard page status, the underlying page protection takes over. If a guard page exception occurs during a system service, the service typically returns a failure status indicator.
PAGE_NOACCESS	Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE	Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be specified as "no cache." This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
pfdwOldProtect

Points to a variable that the function sets to the previous access protection value of the first page in the specified region of pages. If this parameter is NULL or does not point to a valid variable, the function fails.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

You can set the access protection value on committed pages only. If the state of any page in the specified region is not committed, the function fails and returns without modifying the access protection of any pages in the specified region.

The VirtualProtect function changes the access protection of memory in the calling process, and the VirtualProtectEx function changes the access protection of memory in a specified process.

The PAGE_GUARD protection modifier flag establishes guard pages. Guard pages act as one-shot access alarms.

See Also

VirtualAlloc, VirtualProtectEx


VirtualProtectEx

The VirtualProtectEx function changes the access protection on a region of committed pages in the virtual address space of a specified process. Note that this function differs from VirtualProtect, which changes the access protection on the calling process only.

BOOL VirtualProtectEx(

HANDLE  hProcess,	// handle of process
LPVOID  lpvAddress,	// address of region of committed pages
DWORD  cbSize,	// size of region
DWORD  fdwNewProtect,	// desired access protection
PDWORD  pfdwOldProtect	// address of variable to get old protection
);
Parameters

hProcess

Identifies the process whose memory protection is to be changed. The handle must have PROCESS_VM_OPERATION access. For more information on PROCESS_VM_OPERATION, see OpenProcess.

lpvAddress

Points to the base address of the region of pages whose access protection attributes are to be 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 execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE	Enables both read and write access to the committed region of pages.
PAGE_WRITECOPY	Gives copy-on-write access to the committed region of pages.
PAGE_EXECUTE	Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ	Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE	Enables execute, read, and write access to the committed region of pages.
PAGE_EXECUTE_WRITECOPY	Enables execute, read, and write access to the committed region of pages. The pages are shared read-on-write and copy-on-write.
PAGE_GUARD	Pages in the region become guard pages. Any attempt to read from or write to a guard page causes the operating system to raise a STATUS_GUARD_PAGE exception, and turn off the guard page status. Guard pages thus act as a one-shot access alarm. The PAGE_GUARD flag is a page protection modifier. An application uses it with one of the other page protection flags, with one exception: it cannot be used with PAGE_NOACCESS. When an access attempt leads the operating system to turn off guard page status, the underlying page protection takes over. If a guard page exception occurs during a system service, the service typically returns a failure status indicator.
PAGE_NOACCESS	Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE	Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be set to "no cache." This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
pfdwOldProtect

Points to a variable that receives the previous access protection of the first page in the specified region of pages. If this parameter is NULL or does not point to a valid variable, the function fails.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The access protection value can be set only on committed pages. If the state of any page in the specified region is not committed, the function fails and returns without modifying the access protection of any pages in the specified region.

VirtualProtectEx is identical to the VirtualProtect function except that it changes the access protection of memory in a specified process.

The PAGE_GUARD protection modifier flag establishes guard pages. Guard pages act as one-shot access alarms.

See Also

VirtualAlloc, VirtualProtect, VirtualQueryEx


VirtualQuery

The VirtualQuery function provides information about a range of pages in the virtual address space of the calling process.

DWORD VirtualQuery(

LPCVOID  lpvAddress,	// address of region
PMEMORY_BASIC_INFORMATION  pmbiBuffer,	// address of information buffer
DWORD  cbLength	// size of buffer
);
Parameters

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.

Return Value

The return value is the actual number of bytes returned in the information buffer.

Remarks

VirtualQuery provides information about a region of consecutive pages beginning at a specified address that share the following attributes:

•	The state of all pages is the same with the MEM_COMMIT, MEM_RESERVE, MEM_FREE, MEM_PRIVATE, MEM_MAPPED, or MEM_IMAGE flag.

•	If the initial page is not free, all pages in the region are part of the same initial allocation of pages reserved by a call to the VirtualAlloc function.

•	The access of all pages is the same with the PAGE_READONLY, PAGE_READWRITE, PAGE_NOACCESS, PAGE_WRITECOPY, PAGE_EXECUTE, PAGE_EXECUTE_READ, PAGE_EXECUTE_READWRITE, PAGE_EXECUTE_WRITECOPY, PAGE_GUARD, or PAGE_NOCACHE flag.

The function determines the attributes of the first page in the region and then scans subsequent pages until it scans the entire range of pages or until it encounters a page with a nonmatching set of attributes. The function returns the attributes and the size, in bytes, of the region of pages with matching attributes. For example, if there is a 40 megabyte (MB) region of free memory, and VirtualQuery is called on a page that is 10 MB into the region, the function will obtain a state of MEM_FREE and a size of 30 MB.

This function reports on a region of pages in the memory of the calling process, and the VirtualQueryEx function reports on a region of pages in the memory of a specified process.

See Also

GetSystemInfo, MEMORY_BASIC_INFORMATION, VirtualQueryEx


VirtualQueryEx

The VirtualQueryEx function provides information about a range of pages within the virtual address space of a specified process.

DWORD VirtualQueryEx(

HANDLE  hProcess,	// handle of process
LPCVOID  lpvAddress,	// address of region
PMEMORY_BASIC_INFORMATION  pmbiBuffer,	// address of information buffer
DWORD  cbLength	// size of buffer
);
Parameters

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.

Return Value

The return value is the actual number of bytes returned in the information buffer.

Remarks

VirtualQueryEx provides information about a region of consecutive pages beginning at a specified address that share the following attributes:

•	The state of all pages is the same with the MEM_COMMIT, MEM_RESERVE, MEM_FREE, MEM_PRIVATE, MEM_MAPPED, or MEM_IMAGE flag.

•	If the initial page is not free, all pages in the region are part of the same initial allocation of pages reserved by a call to the VirtualAlloc function.

•	The access of all pages is the same with the PAGE_READONLY, PAGE_READWRITE, PAGE_NOACCESS, PAGE_WRITECOPY, PAGE_EXECUTE, PAGE_EXECUTE_READ, PAGE_EXECUTE_READWRITE, PAGE_EXECUTE_WRITECOPY, PAGE_GUARD, or PAGE_NOCACHE flag.

The VirtualQueryEx function determines the attributes of the first page in the region and then scans subsequent pages until it scans the entire range of pages, or until it encounters a page with a nonmatching set of attributes. The function returns the attributes and the size, in bytes, of the region of pages with matching attributes. For example, if there is a 40 megabyte (MB) region of free memory, and VirtualQueryEx is called on a page that is 10 MB into the region, the function will obtain a state of MEM_FREE and a size of 30 MB.

This function is identical to the VirtualQuery function, except that it enables access to information about memory in a specified process.

See Also

GetSystemInfo, MEMORY_BASIC_INFORMATION, VirtualAlloc, VirtualProtectEx, VirtualQuery


VirtualUnlock

The VirtualUnlock function unlocks a specified range of pages in the virtual address space of a process, enabling the system to swap the pages out to the paging file if necessary.

BOOL VirtualUnlock(

LPVOID  lpvAddress,	// address of first byte of range
DWORD  cbSize	// number of bytes in range
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

For the function to succeed, the range specified need not match a range passed to a previous call to the VirtualLock function, but all pages in the range must be locked.

See Also

VirtualLock


VkKeyScan

The VkKeyScan function translates a character to the corresponding virtual-key code and shift state for the current keyboard.

SHORT VkKeyScan(

TCHAR  ch	// character to translate
);
Parameters

ch

Specifies the character to be translated into a virtual-key code.

Return Value

If the function succeeds, the low-order byte of the return value contains the virtual-key code and the high-order byte contains the shift state, which can be a combination of the following flag bits:

Bit	Meaning
1	Either SHIFT key is pressed.
2	Either CTRL key is pressed.
4	Either ALT key is pressed.
If the function finds no key that translates to the passed character code, both the low-order and high-order bytes contain −1.

Remarks

For keyboard layouts that use the right-hand ALT key as a shift key (for example, the French keyboard layout), the shift state is represented by the value 6, because the right-hand ALT key is converted internally into CTRL+ALT.

Translations for the numeric keypad (VK_NUMPAD0 through VK_DIVIDE) are ignored. This function is intended to translate characters into keystrokes from the main keyboard section only. For example, the character "7" is translated into VK_7, not VK_NUMPAD7.

VkKeyScan is used by applications that send characters by using the WM_KEYUP and WM_KEYDOWN messages.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyNameText, GetKeyState, SetKeyboardState, WM_KEYDOWN, WM_KEYUP


VkKeyScanEx  (preliminaryWindows 95)
VkKeyScanEx  (preliminary−Windows 95)

The VkKeyScanEx function translates a character to the corresponding virtual-key code and shift state. The function translates the character using the input language and physical keyboard layout identified by the given keyboard layout handle.

SHORT VkKeyScanEx(

UINT  uChar,	// character to translate
HKL  hkl	// keyboard layout handle
);
Parameters

uChar

Specifies the character to be translated into a virtual-key code.

hkl

Identifies the keyboard layout to use to translate the character. This parameter can be any keyboard layout handle previously returned by the LoadKeyboardLayout function.

Return Value

If the function succeeds, the low-order byte of the return value contains the virtual-key code and the high-order byte contains the shift state, which can be a combination of the following flag bits:

Bit	Meaning
1	Either SHIFT key is pressed.
2	Either CTRL key is pressed.
4	Either ALT key is pressed.
If the function finds no key that translates to the passed character code, both the low-order and high-order bytes contain −1.

Remarks

For keyboard layouts that use the right-hand ALT key as a shift key (for example, the French keyboard layout), the shift state is represented by the value 6, because the right-hand Alt key is converted internally into CTRL+ALT.

Translations for the numeric keypad (VK_NUMPAD0 through VK_DIVIDE) are ignored. This function is intended to translate characters into keystrokes from the main keyboard section only. For example, the character "7" is translated into VK_7, not VK_NUMPAD7.

VkKeyScanEx is used by applications that send characters by using the WM_KEYUP and WM_KEYDOWN messages.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyNameText, GetKeyState, LoadKeyboardLayout, SetKeyboardState, ToAsciiEx, VkKeyScan


WaitCommEvent

The WaitCommEvent function waits for an event to occur for a specified communications device. The set of events that are monitored by this function is contained in the event mask associated with the device handle.

BOOL WaitCommEvent(

HANDLE  hCommDev,	// handle of communications device
LPDWORD  lpfdwEvtMask,	// address of variable for event that occurred
LPOVERLAPPED  lpo,	// address of overlapped structure
);
Parameters

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	A character was received and placed in the input buffer.
EV_RXFLAG	The event character was received and placed in the input buffer. The event character is specified in the device's DCB structure, which is applied to a serial port by using the SetCommState function.
EV_TXEMPTY	The last character in the output buffer was sent.
lpo

Points to an OVERLAPPED structure. This parameter is ignored if the hCommDev handle was opened without specifying the FILE_FLAG_OVERLAPPED flag. If an overlapped operation is not desired, this parameter can be NULL.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

The 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, WaitCommEvent 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 the GetLastError function returns ERROR_IO_PENDING, indicating that the operation is executing in the background. When this happens, the system sets the hEvent member of the OVERLAPPED structure to the not-signaled state before WaitCommEvent returns, and then it sets it to the signaled state when one of the specified events or an error occurs. The calling process can use a wait function to determine the event object's state and then use the GetOverlappedResult function to determine the results of the WaitCommEvent operation. GetOverlappedResult reports the success or failure of the operation, and the variable pointed to by the 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 an overlapped WaitCommEvent operation is in progress, WaitCommEvent returns immediately. The variable pointed to by the lpfdwEvtMask parameter is set to zero.

See Also

CreateFile, DCB, GetCommMask, GetOverlappedResult, OVERLAPPED, SetCommMask, SetCommState


WaitForDebugEvent

The WaitForDebugEvent function waits for a debugging event to occur in a process being debugged.

BOOL WaitForDebugEvent(

LPDEBUG_EVENT  lpde,	// address of structure for event information
DWORD  dwTimeout	// number of milliseconds to wait for event
);
Parameters

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 this parameter is zero, the function tests for a debugging event and returns immediately. If the parameter is INFINITE, the function does not return until a debugging event has occurred.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Only the thread that created the process being debugged can call WaitForDebugEvent.

See Also

ContinueDebugEvent, CreateProcess, DebugActiveProcess, DebugBreak, DEBUG_EVENT, OutputDebugString


WaitForInputIdle

The WaitForInputIdle function waits until the given process is waiting for user input with no input pending, or until the time-out interval has elapsed.

The WaitForInputIdle function only works with GUI applications. If a console application calls the function, it returns immediately, with no wait.

DWORD WaitForInputIdle(

HANDLE  hProcess,	// handle to process
DWORD  dwTimeout	// time-out interval in milliseconds
);
Parameters

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.

Return Value

The following table shows the possible return values:

Value	Meaning
0	The wait was satisfied successfully.
WAIT_TIMEOUT	The wait was terminated because the time-out interval elapsed.
0xFFFFFFFF	An error occurred. To get extended error information, use the GetLastError function.
Remarks

The WaitForInputIdle function enables a thread to suspend its execution until a specified process has finished its initialization and is waiting for user input with no input pending. This can be useful for synchronizing a parent process and a newly created child process. When a parent process creates a child process, the CreateProcess function returns without waiting for the child process to finish its initialization. Before trying to communicate with the child process, the parent process can use WaitForInputIdle to determine when the child's initialization has been completed. For example, the parent process should use WaitForInputIdle before trying to find a window associated with the child process.

The WaitForInputIdle function can be used at any time, not just during application startup.

See Also

CreateProcess


WaitForMultipleObjects

The WaitForMultipleObjects function returns either when any one or when all of the specified objects are in the signaled state, or when the time-out interval elapses.

DWORD WaitForMultipleObjects(

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
);
Parameters

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 following Remarks section. The array can contain handles of objects of different types.

Windows NT: The handles must have SYNCHRONIZE access.

fWaitAll

Specifies the wait type. If TRUE, the function returns when 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.

Return Value

If the function succeeds, the return value indicates the event that caused the function to return.

If the function fails, the return value is WAIT_FAILED. To get extended error information, call GetLastError.

The return value upon success is one of the following values:

Value	Meaning
WAIT_OBJECT_0 to (WAIT_OBJECT_0 + 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.
Remarks

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.
An abandoned mutex object is not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.

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.

See Also

CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, FindFirstChangeNotification, GetStdHandle, MsgWaitForMultipleObjects, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, PulseEvent, ResetEvent, SetEvent, Sleep, WaitForMultipleObjectsEx, WaitForSingleObject


WaitForMultipleObjectsEx

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

DWORD WaitForMultipleObjectsEx(

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
);
Parameters

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 following Remarks section. The array can contain handles of objects of different types.

Windows NT: The handles must have SYNCHRONIZE access.

fWaitAll

Specifies the wait type. If TRUE, the function returns when 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.

Return Value

If the function succeeds, the return value indicates the event that caused the function to return.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

The return value on success is one of the following values:

Value	Meaning
WAIT_OBJECT_0 to (WAIT_OBJECT_0 + 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.
Remarks

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, using 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.
An abandoned mutex object is not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.

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.

See Also

CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, FindFirstChangeNotification, GetStdHandle, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, MsgWaitForMultipleObjects, PulseEvent, ReadFileEx, ResetEvent, SetEvent, SleepEx, WaitForMultipleObjects, WaitForSingleObjectEx, WriteFileEx


WaitForPrinterChange

The WaitForPrinterChange function returns when one or more requested changes occur on a printer or print server, or if the function times out.

DWORD WaitForPrinterChange(

HANDLE  hPrinter,	// handle of printer object
DWORD  Flags	// bitmask with changes to wait for
);
Parameters

hPrinter

Identifies the printer to wait for.

Flags

Specifies a bitmask with the changes that the application wishes to be notified about. In addition to the values listed in the Return Value section, the following printer change values have meaning:

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.
Return Value

If the function succeeds, the return value is a bitmask 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.

Remarks

If the WaitForPrinterChange 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.

An application that needs an asynchronous, more resource-efficient alternative to the WaitForPrinterChange function should use the three Find*PrinterChangeNotification functions, in combination with the wait functions.

See Also

ClosePrinter, EnumForms, EnumJobs, EnumMonitors, EnumPrinterDrivers, EnumPrinters, EnumPrintProcessors, FindClosePrinterChangeNotification, FindFirstPrinterChangeNotification, FindNextPrinterChangeNotification, GetPrinter, OpenPrinter, Sleep


WaitForSingleObject

The WaitForSingleObject function returns when the specified object is in the signaled state or when the time-out interval elapses.

DWORD WaitForSingleObject(

HANDLE  hObject,	// handle of object to wait for
DWORD  dwTimeout	// time-out interval in milliseconds
);
Parameters

hObject

Identifies the object. For a list of the object types whose handles can be specified, see the following Remarks section.

Windows NT: The handle must have SYNCHRONIZE access.

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.

Return Value

If the function succeeds, the return value indicates the event that caused the function to return.

If the function fails, the return value is WAIT_FAILED. To get extended error information, call GetLastError.

The return value on success is one of the following values:

Value	Meaning
WAIT_ABANDONED	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.
WAIT_OBJECT_0	The state of the specified object is signaled.
WAIT_TIMEOUT	The time-out interval elapsed, and the object's state is nonsignaled.
Remarks

The WaitForSingleObject function checks the current state of the specified object. If the object's state is nonsignaled, the calling thread enters an efficient wait state. The thread consumes very little processor time while waiting for 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.

See Also

CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, FindFirstChangeNotification, GetStdHandle, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, PulseEvent, ResetEvent, SetEvent, Sleep, WaitForMultipleObjects, WaitForSingleObjectEx


WaitForSingleObjectEx

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

DWORD WaitForSingleObjectEx(

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
);
Parameters

hObject

Identifies the object. For a list of the object types whose handles can be specified, see the following Remarks section.

Windows NT: The handle must have SYNCHRONIZE access.

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.

Return Value

If the function succeeds, the return value indicates the event that caused the function to return.

If the function fails, the return value is 0xFFFFFFFF. To get extended error information, call GetLastError.

The successful return value is one of the following:

Value	Meaning
WAIT_OBJECT_0	The state of the specified object is signaled.
WAIT_ABANDONED	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.
WAIT_IO_COMPLETION	One or more I/O completion routines are queued for execution.
WAIT_TIMEOUT	The time-out interval elapsed, and the object's state is nonsignaled.
Remarks

The WaitForSingleObjectEx function determines whether the 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.

See Also

CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, FindFirstChangeNotification, GetStdHandle, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, PulseEvent, ReadFileEx, ResetEvent, SetEvent, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObject, WriteFileEx


WaitMessage

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.

Parameters

This function has no parameters.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

GetMessage, PeekMessage


WaitNamedPipe

The WaitNamedPipe function waits until either a time-out interval elapses or an instance of the specified named pipe is available to be connected to (that is, the pipe's server process has a pending ConnectNamedPipe operation on the pipe).

BOOL WaitNamedPipe(

LPCTSTR  lpszPipeName,	// address of name of pipe to wait for
DWORD  dwTimeout	// time-out interval, in milliseconds
);
Parameters

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. The following pipe name format is used:

\\servername\pipe\pipename

dwTimeout

Specifies the number of milliseconds that the function will wait for an instance of the named pipe to be available. One of the following values can be used instead of specifying a number of milliseconds:

Value	Meaning
NMPWAIT_USE_DEFAULT_WAIT	The time-out interval is the default value specified by the server process in the CreateNamedPipe function.
NMPWAIT_WAIT_FOREVER	The function does not return until an instance of the named pipe is available.
Return Value

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, call GetLastError.

Remarks

If no instances of the specified named pipe exist, the WaitNamedPipe function returns immediately, regardless of the time-out value.

If the function succeeds, the process should use the CreateFile function to open a handle to the named pipe. A return value of TRUE indicates that there is at least one instance of the pipe available. A subsequent CreateFile call to the pipe can fail, because the instance was closed by the server or opened by another client.

See Also

CallNamedPipe, ConnectNamedPipe, CreateFile, CreateNamedPipe


WaitSoundState

The WaitSoundState function has been deleted.

See Also

Beep, MessageBeep


WideCharToMultiByte

The WideCharToMultiByte function maps a wide-character string to a new character string. The new character string is not necessarily from a multibyte character set.

int WideCharToMultiByte(

UINT  CodePage,	// code page
DWORD  dwFlags,	// performance and mapping flags
LPCWSTR  lpWideCharStr,	// address of wide-character string
int  cchWideChar,	// number of characters in string
LPSTR  lpMultiByteStr,	// address of buffer for new string
int  cchMultiByte,	// size of buffer
LPCSTR  lpDefaultChar,	// address of default for unmappable characters
LPBOOL  lpUsedDefaultChar	// address of flag set when default char. used
);
Parameters

CodePage

Specifies the code page used to perform the conversion. This parameter can be given the value of any codepage that is installed or available in the system. The following values may be used to specify one of the system default code pages:

Value	Meaning
CP_ACP	ANSI code page
CP_MACCP	Macintosh code page
CP_OEMCP	OEM code page
dwFlags

A set of bit flags that specify the handling of unmapped characters. The function performs more quickly when none of these flags is set. The following flag constants are defined:

Value	Meaning
WC_COMPOSITECHECK	Convert composite characters to precomposed characters.
WC_DISCARDNS	Discard nonspacing characters during conversion.
WC_SEPCHARS	Generate separate characters during conversion. This is the default conversion behavior.
WC_DEFAULTCHAR	Replace exceptions with the default character during conversion.
When WC_COMPOSITECHECK is specified, the function converts composite characters to precomposed characters. A composite character consists of a base character and a nonspacing character, each having different character values. A precomposed character has a single character value for a base/nonspacing character combination. In the character è, the e is the base character, and the accent grave mark is the nonspacing character.

When an application specifies WC_COMPOSITECHECK, it can use the last 3 flags in this list (WC_DISCARDNS, WC_SEPCHARS, and WC_DEFAULTCHAR) to customize the conversion to precomposed characters. These flags determine the function's behavior when there is no precomposed mapping for a base/nonspace character combination in a wide-character string. These last 3 flags can only be used if the WC_COMPOSITECHECK flag is set.

The function's default behavior is to generate separate characters (WC_SEPCHARS) for unmapped composite characters.

lpWideCharStr

Points to the wide-character string to be converted.

cchWideChar

Specifies the number of characters in the string pointed to by the lpWideCharStr parameter. If this value is −1, the string is assumed to be null-terminated and the length is calculated automatically.

lpMultiByteStr

Points to the buffer to receive the translated string.

cchMultiByte

Specifies the size in characters of the buffer pointed to by the lpMultiByteStr parameter. If this value is zero, the function returns the number of bytes required for the buffer. (In this case, the lpMultiByteStr buffer is not used.)

lpDefaultChar

Points to the character used if a wide character cannot be represented in the specified code page. If this parameter is NULL, a system default value is used. The function is faster when both lpDefaultChar and lpUsedDefaultChar are NULL.

lpUsedDefaultChar

Points to a flag that indicates whether a default character was used. The flag is set to TRUE if one or more wide characters in the source string cannot be represented in the specified code page. Otherwise, the flag is set to FALSE. This parameter may be NULL. The function is faster when both lpDefaultChar and lpUsedDefaultChar are NULL.

Return Value

If the function succeeds, and cchMultiByte is nonzero, the return value is the number of characters 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. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

Remarks

The lpMultiByteStr and lpWideCharStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

An application can use the lpDefaultChar parameter to change the default character used for the conversion.

As noted earlier, the WideCharToMultiByte function operates most efficiently when both lpDefaultChar and lpUsedDefaultChar are NULL. The following table shows the behavior of WideCharToMultiByte for the four combinations of lpDefaultChar and lpUsedDefaultChar :

lpDefaultChar	lpUsedDefaultChar	Result
NULL	NULL	No default checking. This is the most efficient, quick way to use this function.
non-NULL	NULL	Uses the specified default character, but does not set lpUsedDefaultChar
NULL	non-NULL	Uses the system default character and sets lpUsedDefaultChar if necessary.
non-NULL	non-NULL	Uses the specified default character and sets lpUsedDefaultChar if necessary.
See Also

MultiByteToWideChar


WidenPath

The WidenPath function redefines the current path as the area that would be painted if the path were stroked using the pen currently selected into the given device context.

BOOL WidenPath(

HDC  hdc	// handle of device context
);
Parameters

hdc

Identifies a device context that contains a closed path.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_CAN_NOT_COMPLETE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY

Remarks

The WidenPath function is successful only if the current pen is a geometric pen created by the ExtCreatePen function, or if the pen is created with the CreatePen function and has a width, in device units, of more than one.

The device context identified by the hdc parameter must contain a closed path.

Any Bézier curves in the path are converted to sequences of straight lines approximating the widened curves. As such, no Bézier curves remain in the path after WidenPath is called.

See Also

BeginPath, CreatePen, EndPath, ExtCreatePen, SetMiterLimit


WindowFromDC

The WindowFromDC function returns the handle of the window associated with the given display device context (DC). Output functions that use the given device context draw into this window.

HWND WindowFromDC(

HDC  hdc	// handle of window
);
Parameters

hdc

Identifies the device context from which a handle for the associated window is to be retrieved.

Return Value

If the function succeeds, the return value is the handle of the window associated with the given display device context.

If the function fails, the return value is NULL.

See Also

GetDC, GetDCEx, GetWindowDC


WindowFromPoint

The WindowFromPoint function retrieves the handle of the window that contains the specified point.

HWND WindowFromPoint(

POINT  pt	// structure with point
);
Parameters

pt

Specifies a POINT structure that defines the point to be checked.

Return Value

If the function succeeds, the return value is the handle of the window that contains the point. If no window exists at the given point, the return value is NULL.

Remarks

The WindowFromPoint function does not retrieve the handle of a hidden or disabled window, even if the point is within the window. An application should use the ChildWindowFromPoint function for a nonrestrictive search.

See Also

ChildWindowFromPoint, POINT, WindowFromDC


WindowProc

The WindowProc function is an application-defined callback function that processes messages sent to a window.

LRESULT CALLBACK WindowProc(

HWND  hwnd,	// handle of window
UINT  uMsg,	// message identifier
WPARAM  wParam,	// first message parameter
LPARAM  lParam	// second message parameter
);
Parameters

hwnd

Identifies the window.

uMsg

Specifies the message.

wParam

Specifies additional message information. The contents of this parameter depend on the value of the uMsg parameter.

lParam

Specifies additional message information. The contents of this parameter depend on the value of the uMsg parameter.

Return Value

The return value is the result of the message processing and depends on the message sent.

Remarks

WindowProc is a placeholder for the application-defined function name.

See Also

CallWindowProc, DefWindowProc, RegisterClass


WinExec

The WinExec function runs the specified application.

This function is provided for compatibility with earlier versions of Windows. For Win32-based applications, use the CreateProcess function.

UINT WinExec(

LPCSTR  lpszCmdLine,	// address of command line
UINT  fuCmdShow	// window style for new application
);
Parameters

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 parameter does not contain a directory path, Windows searches for the executable file in this sequence:

1.	The directory from which the application loaded.

2.	The current directory.

3.	The Windows system directory. The GetSystemDirectory function retrieves the path of this directory.

4.	The Windows directory. The GetWindowsDirectory function retrieves the path of this directory.

5.	The directories listed in the PATH environment variable.

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 the CreateProcess function. For a list of the acceptable values, see the description of the nCmdShow parameter of the ShowWindow function. For a non-Windows − based application, the PIF file, if any, for the application determines the window state.

Return Value

If the function succeeds, the return value is greater than 31.

If the function fails, the return value is one of the following error values:

Value	Meaning
0	The system is out of memory or resources.
ERROR_BAD_FORMAT	The .EXE file is invalid (non-Win32 .EXE or error in .EXE image).
ERROR_FILE_NOT_FOUND	The specified file was not found.
ERROR_PATH_NOT_FOUND	The specified path was not found.
Remarks

Win32-based applications should use the CreateProcess function rather than this function. The WinExec function exists in Win32 to provide compatibility with earlier versions of Windows. For more information about how the WinExec function is implemented, see the Remarks section of the LoadModule function.

In Win32, the WinExec function returns when the launched process calls the GetMessage function or a time-out limit is reached. To avoid waiting for the time out delay, call the GetMessage function as soon as possible in any process launched by a call to WinExec.

See Also

CreateProcess, GetMessage, GetSystemDirectory, GetWindowsDirectory, LoadModule, ShowWindow


WinHelp

The WinHelp function starts Windows Help (WINHELP.EXE) and passes additional data indicating the nature of the help requested by the application. The application specifies the name and, where required, the directory path of the help file to display.

BOOL WinHelp(

HWND  hwnd,	// handle of window requesting Help
LPCTSTR  lpszHelp,	// address of directory-path string
UINT  uCommand,	// type of Help
DWORD  dwData	// additional data
);
Parameters

hwnd

Identifies the window requesting Help. The WinHelp function uses this handle to keep track of which applications have requested Help.

lpszHelp

Points to a null-terminated string containing the path, if necessary, and the name of the Help file that the Help application is to display.

The filename may be followed by an angle bracket (>) and the name of a secondary window if the topic is to be displayed in a secondary window rather than in the primary window. The name of the secondary window must have been defined in the [WINDOWS] section of the Help project (.HPJ) file.

uCommand

Specifies the type of help requested. For a list of possible values and how they affect the value to place in the dwData parameter, see the Remarks section.

dwData

Specifies additional data. The value used depends on the value of the uCommand parameter. For a list of possible values, see the Remarks section.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

Before closing the window that requested Help, the application must call WinHelp with the uCommand parameter set to HELP_QUIT. Until all applications have done this, Windows Help will not terminate. Note that calling WinHelp with the HELP_QUIT command is not necessary if you used the HELP_CONTEXTPOPUP command to start Help

The following table shows the possible values for the uCommand parameter and the corresponding formats of the dwData parameter:

uCommand	Action	dwData
HELP_COMMAND	Executes a Help macro or macro string.	Address of a string that specifies the name of the Help macro(s) to execute. If the string specifies multiple macros names, the names must be separated by semicolons. You must use the short form of the macro name for some macros because Help does not support the long name.
HELP_CONTENTS	Displays the topic specified by the Contents option in the [OPTIONS] section of the .HPJ file. This is for backward compatibility. New applications should provide a .CNT file and use the HELP_FINDER command.	Ignored, set to 0.
HELP_CONTEXT	Displays the topic identified by the specified context identifier defined in the [MAP] section of the .HPJ file.	Unsigned long integer containing the context identifier for the topic.
HELP_CONTEXTPOPUP	Displays, in a pop-up window, the topic identified by the specified context identifier defined in the [MAP] section of the .HPJ file.	Unsigned long integer containing the context identifier for a topic.
HELP_FORCEFILE	Ensures that WinHelp is displaying the correct help file. If the incorrect help file is being displayed, WinHelp opens the correct one; otherwise, there is no action.	Ignored, set to 0.
HELP_HELPONHELP	Displays help on how to use Windows Help, if the WINHELP.HLP file is available.	Ignored, set to 0.
HELP_INDEX	Displays the Index in the Help Topics dialog box. This command is for backward compatibility. New applications should use the HELP_FINDER command.	Ignored, set to 0.
HELP_KEY	Displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, displays the Index with the topics listed in the Topics Found list box.	Address of a keyword string.
HELP_MULTIKEY	Displays the topic specified by a keyword in an alternative keyword table.	Address of a MULTIKEYHELP structure that specifies a table footnote character and a keyword.
HELP_PARTIALKEY	Displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, displays the Index tab. To display the Index without passing a keyword (the third result), you should use a pointer to an empty string.	Address of a keyword  string.
HELP_QUIT	Informs the Help application that it is no longer needed. If no other applications have asked for Help, Windows closes the Help application.	Ignored, set to 0.
HELP_SETCONTENTS	Specifies the Contents topic. The Help application displays this topic when the user clicks the Contents button.	Unsigned long integer containing the context identifier for the Contents topic.
HELP_SETINDEX	Specifies a keyword table to be displayed in the Index of the Help Topics dialog box.	Unsigned long integer containing the context identifier for the Index topic.
HELP_SETWINPOS	Displays the Help window, if it is minimized or in memory, and sets its size and position as specified.	Address of a HELPWININFO structure that specifies the size and position of either a primary or secondary Help window.
See Also

HELPWININFO, MULTIKEYHELP


WinMain

The WinMain function is called by the system as the initial entry point for a Windows-based application.

int WinMain(

HINSTANCE  hInstance,	// handle of current instance
HINSTANCE  hPrevInstance,	// handle of previous instance
LPSTR  lpszCmdLine,	// address of command line
int  nCmdShow	// show state of window
);
Parameters

hInstance

Identifies the current instance of the application.

hPrevInstance

Identifies the previous instance of the application. For a Win32-based application, this parameter is always NULL.

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

If the function succeeds, terminating when it receives a WM_QUIT message, it should return the exit value contained in that message's wParam parameter. If the function terminates before entering the message loop, it should return 0.

Remarks

WinMain initializes an application, 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


WNetAddConnection

The WNetAddConnection function enables the calling application to connect a local device to a network resource. A successful connection is persistent, meaning that Windows automatically restores the connection during subsequent logon operations.

This function is provided for compatibility with earlier versions of Microsoft Windows. For new applications, use the WNetAddConnection2 function.

DWORD WNetAddConnection(

LPTSTR  lpszRemoteName,	// address of network device name
LPTSTR  lpszPassword,	// address of password
LPTSTR  lpszLocalName	// address of local device name
);
Parameters

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 parameter is usually the password associated with the current user.

If this parameter is NULL, the default password is used. If the string is empty, no password is used.

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.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_ACCESS_DENIED	Access is denied.
ERROR_ALREADY_ASSIGNED	The device specified in the 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 the lpszRemoteName parameter is not valid or cannot be located.
ERROR_BAD_PROFILE	The user profile is in an incorrect format.
ERROR_CANNOT_OPEN_PROFILE	The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_ALREADY_REMEMBERED	An entry for the device specified in lpszLocalName is already in the user profile.
ERROR_EXTENDED_ERROR	A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_INVALID_PASSWORD	The specified password is invalid.
ERROR_NO_NET_OR_BAD_PATH	The operation cannot be performed because either a network component is not started or the specified name cannot be used.
ERROR_NO_NETWORK	The network is not present.
The function returns error codes and sets the error code values returned by GetLastError.

See Also

WNetAddConnection2, WNetCancelConnection, WNetCancelConnection2, WNetGetConnection, WNetGetLastError


WNetAddConnection2

The WNetAddConnection2 function makes a connection to a network resource. The function can redirect a local device to the network resource.

The WNetAddConnection2 function supersedes the WNetAddConnection function. If you pass a handle to a window that the provider of network resources can use as an owner window for dialog boxes, use the WNetAddConnection3 function.

DWORD WNetAddConnection2(

LPNETRESOURCE  lpNetResource,	// points to structure that specifies connection details
LPCTSTR  lpPassword,	// points to password string
LPCTSTR  lpUsername,	// points to user name string
DWORD  fdwConnection	// set of bit flags that specify connection options
);
Parameters

lpNetResource

Points to a NETRESOURCE structure that specifies details of the proposed connection: information about the network resource, the local device, and the network resource provider.

You must specify the following members of the NETRESOURCE structure:

Member	Description
dwType	Specifies the type of network resource to connect to. If lpLocalName points to a non-empty string, this member can be RESOURCETYPE_DISK or RESOURCETYPE_PRINT. If lpLocalName is NULL or points to an empty string, dwType can be RESOURCETYPE_DISK, RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.
lpLocalName	Points to a null-terminated string that specifies the name of a local device to be redirected, such as "F:" or "LPT1". The string is treated in a case-insensitive manner. If the string is empty or lpLocalName is NULL, the function makes a connection to the network resource without redirecting a local device.
lpRemoteName	Points to a null-terminated string that specifies the network resource to connect to. The string can be up to MAX_PATH characters in length. The string must follow the network provider's naming conventions.
lpProvider	Points to a null-terminated string that specifies the network provider to connect to. If lpProvider is NULL or points to an empty string, the operating system attempts to determine the correct provider by parsing the string pointed to by lpRemoteName.
	You should set this member only if you know for sure which network provider you want to use. Otherwise, let the operating system determine which provider the network name maps to.
	If this member is not NULL, the operating system attempts to make a connection only to the named network provider.
The WNetAddConnection2 function ignores the other members of the NETRESOURCE structure.

lpPassword

Points to a null-terminated string that specifies a password to be used in making the network connection.

If lpPassword is NULL, the function uses the current default password associated with the user specified by lpUserName.

If lpPassword points to an empty string, the function does not use a password.

lpUsername

Points to a null-terminated string that specifies a user name to be used in making the connection.

If lpUserName is NULL, the function uses the default user name. The user context for the process provides the default user name.

The lpUserName parameter is specified when users want to connect to a network resource for which they have been assigned a user name or account other than the default user name or account.

The user-name string represents a security context. It may be specific to a network provider.

fdwConnection

A set of bit flags that specify connection options. The following bit flag constant is currently defined:

Value	Meaning
CONNECT_UPDATE_PROFILE	The network resource connection should be remembered.  If this bit flag is set, the operating system automatically attempts to restore the connection when the user logs on. The operating system remembers only successful connections that redirect local devices. It does not remember unsuccessful connections or deviceless connections. A deviceless connection occurs when lpLocalName is NULL or points to an empty string. If this bit flag is clear, the operating system will not automatically restore the connection at logon.
Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. Returning an error code provides compatibility with the behavior of the Windows 3.1 function WNetAddConnection. You can also call the GetLastError function to obtain the (same) error code. One of the following error codes may be returned when WNetAddConnection2 fails:

Value	Meaning
ERROR_ACCESS_DENIED	Access to the network resource was denied.
ERROR_ALREADY_ASSIGNED	The local device specified by lpLocalName is already connected to a network resource.
ERROR_BAD_DEV_TYPE	The type of local device and the type of network resource do not match.
ERROR_BAD_DEVICE	The value specified by lpLocalName is invalid.
ERROR_BAD_NET_NAME	The value specified by lpRemoteName is not acceptable to any network resource provider. The resource name is invalid, or the named resource cannot be located.
ERROR_BAD_PROFILE	The user profile is in an incorrect format.
ERROR_BAD_PROVIDER	The value specified by lpProvider does not match any provider.
ERROR_BUSY	The router or provider is busy, possibly initializing. The caller should retry.
ERROR_CANCELLED	The attempt to make the connection was cancelled by the user through a dialog box from one of the network resource providers, or by a called resource.
ERROR_CANNOT_OPEN_PROFILE	The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_ALREADY_REMEMBERED	An entry for the device specified in lpLocalName is already in the user profile.
ERROR_EXTENDED_ERROR	A network-specific error occured. Call the WNetGetLastError function to get a description of the error.
ERROR_INVALID_PASSWORD	The specified password is invalid.
ERROR_NO_NET_OR_BAD_PATH	A network component has not started, or the specified name could not be handled.
ERROR_NO_NETWORK	There is no network present.
See Also

WNetAddConnection, WNetAddConnection3, WNetCancelConnection2, WNetGetConnection, WNetGetLastError, NETRESOURCE


WNetAddConnection3

The WNetAddConnection3 function makes a connection to a network resource. The function can redirect a local device to the network resource.

The WNetAddConnection3 function is similar to the WNetAddConnection2 function. The main difference is that WNetAddConnection3 has an additional parameter, a handle to a window that the provider of network resources can use as an owner window for dialog boxes.

DWORD WNetAddConnection3(

HWND  hwndOwner,	// handle to an owner window for network provider dialog boxes
LPNETRESOURCE  lpNetResource,	// address of structure that specifies connection details
LPTSTR  lpPassword,	// address of password string
LPTSTR  lpUserName,	// address of user name string
DWORD  fdwConnection	// set of bit flags that specify connection options
);
Parameters

hwndOwner

Specifies a window that the provider of network resources can use as an owner window for dialog boxes.

The hwndOwner parameter may be NULL. If it is, a call to WNetAddConnection3 is equivalent to calling the WNetAddConnection2 function.

lpNetResource

Points to a NETRESOURCE data structure that specifies details of the proposed connection: information about the network resource, the local device, and the network resource provider.

You must specify the following members of the NETRESOURCE structure:

Member	Description
dwType	Specifies the type of network resource to connect to. If lpLocalName points to a non-empty string, this member can be RESOURCETYPE_DISK or RESOURCETYPE_PRINT. If lpLocalName is NULL or points to an empty string, dwType can be RESOURCETYPE_DISK, RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.
lpLocalName	Points to a null-terminated string that specifies the name of a local device to be redirected, such as "F:" or "LPT1". The string is treated in a case-insensitive manner. If the string is empty or lpLocalName is NULL, the function makes a connection to the network resource without redirecting a local device.
lpRemoteName	Points to a null-terminated string that specifies the network resource to connect to. The string can be up to MAX_PATH characters in length . The string must follow the network provider's naming conventions.
lpProvider	Points to a null-terminated string that specifies the network provider to connect to. If lpProvider is NULL or points to an empty string, the operating system attempts to determine the correct provider by parsing the string pointed to by lpRemoteName.
	You should set this member only if you know for sure which network provider you want to use. Otherwise, let the operating system determine which network provider the network name maps to.
	If this member is not NULL, the operating system attempts to make a connection only to the named network provider.
The WNetAddConnection3 function ignores the other members of the NETRESOURCE structure.

lpPassword

Points to a null-terminated string that specifies a password to be used in making the network connection.

If lpPassword is NULL, the function uses the current default password associated with the user specified by lpUserName.

If lpPassword points to an empty string, the function does not use a password.

lpUserName

Points to a null-terminated string that specifies a user name to be used in making the connection.

If lpUserName is NULL, the function uses the default user name. The user context for the process provides the default user name.

The lpUserName parameter is specified when users want to connect to a network resource for which they have been assigned a user name or account other than the default user name or account.

The user-name string represents a security context. It may be specific to a network provider.

fdwConnection

A set of bit flags that specify connection options. The following bit flag constants are currently defined:

Value	Meaning
CONNECT_UPDATE_PROFILE	The network resource connection should be remembered.  If this bit flag is set, the operating system automatically attempts to restore the connection when the user logs on. The operating system remembers only successful connections that redirect local devices. It does not remember unsuccessful connections and deviceless connections. A deviceless connection occurs when lpLocalName is NULL or points to an empty string. If this bit flag is clear, the operating system will not automatically restore the connection at logon.
Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. Returning an error code provides compatibility with the behavior of the Windows 3.1 function WNetAddConnection. You can also call the GetLastError function to obtain the (same) error code. One of the following error codes may be returned when WNetAddConnection3 fails:

Value	Meaning
ERROR_ACCESS_DENIED	Access to the network resource was denied.
ERROR_ALREADY_ASSIGNED	The local device specified by lpLocalName is already connected to a network resource.
ERROR_BAD_DEV_TYPE	The type of local device and the type of network resource do not match.
ERROR_BAD_DEVICE	The value specified by lpLocalName is invalid.
ERROR_BAD_NET_NAME	The value specified by lpRemoteName is not acceptable to any network resource provider. The resource name is invalid, or the named resource cannot be located.
ERROR_BAD_PROFILE	The user profile is in an incorrect format.
ERROR_BAD_PROVIDER	The value specified by lpProvider does not match any provider.
ERROR_BUSY	The router or provider is busy, possibly initializing. The caller should retry.
ERROR_CANCELLED	The attempt to make the connection was cancelled by the user through a dialog box from one of the network resource providers or by a called resource.
ERROR_CANNOT_OPEN_PROFILE	The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_ALREADY_REMEMBERED	An entry for the device specified in lpLocalName is already in the user profile.
ERROR_EXTENDED_ERROR	A network-specific error occured. Call the WNetGetLastError function to get a description of the error.
ERROR_INVALID_PASSWORD	The specified password is invalid.
ERROR_NO_NET_OR_BAD_PATH	A network component has not started, or the specified name could not be handled.
ERROR_NO_NETWORK	There is no network present.
See Also

NETRESOURCE, WNetAddConnection2, WNetCancelConnection2, WNetGetConnection, WNetGetLastError


WNetCancelConnection

The WNetCancelConnection function breaks an existing network connection.

The function is provided for compatibility with earlier versions of Microsoft Windows. For new applications, use the WNetCancelConnection2 function.

DWORD WNetCancelConnection(

LPTSTR  lpszName,	// address of resource name to be disconnected
BOOL  fForce	// flag for unconditional disconnect
);
Parameters

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 this parameter specifies a redirected local device, only the specified redirection is broken, and Windows will not restore the connection during subsequent logon operations. When this parameter 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 this parameter is FALSE, the function fails if there are open files or jobs.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_BAD_PROFILE	The user profile is in an incorrect format.
ERROR_CANNOT_OPEN_PROFILE	The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_IN_USE	The device is in use by an active process and cannot be disconnected.
ERROR_EXTENDED_ERROR	A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_NOT_CONNECTED	The name specified by the lpszName parameter is not a redirected device, or the system is not currently connected to the device specified by the parameter.
ERROR_OPEN_FILES	There are open files, and the fForce parameter is FALSE.
The function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

See Also

WNetAddConnection, WNetAddConnection2, WNetCancelConnection2, WNetGetConnection, WNetGetLastError


WNetCancelConnection2

The WNetCancelConnection2 function breaks an existing network connection. It can also be used to remove remembered network connections that are not currently connected. This function supersedes WNetCancelConnection.

DWORD WNetCancelConnection2(

LPTSTR  lpszName,	// address of resource name to disconnect
DWORD  fdwConnection,	// connection type flags
BOOL  fForce	// flag for unconditional disconnect
);
Parameters

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 this parameter 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 this parameter is FALSE, the function fails if there are open files or jobs.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_BAD_PROFILE	The user profile is in an incorrect format.
ERROR_CANNOT_OPEN_PROFILE	The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_IN_USE	The device is in use by an active process and cannot be disconnected.
ERROR_EXTENDED_ERROR	A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_NOT_CONNECTED	The name specified by the lpszName parameter is not a redirected device, or the system is not currently connected to the device specified by the parameter.
ERROR_OPEN_FILES	There are open files, and the fForce parameter is FALSE.
See Also

WNetAddConnection, WNetAddConnection2, WNetAddConnection3, WNetCancelConnection, WNetGetConnection, WNetGetLastError


WNetCloseEnum

The WNetCloseEnum function ends a network resource enumeration started by the WNetOpenEnum function.

DWORD WNetCloseEnum(

HANDLE  hEnum	// handle of enumeration
);
Parameters

hEnum

Identifies an enumeration instance. This handle must be returned by the WNetOpenEnum function.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_NO_NETWORK	A network is not present. This condition is tested before the handle specified in the hEnum parameter is tested for validity.
ERROR_INVALID_HANDLE	hEnum is not a valid handle.
ERROR_EXTENDED_ERROR	A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
The function returns error codes for compatibility with Windows version 3.1. For compatibility with Windows NT, the function also sets the error code value returned by GetLastError.

See Also

WNetEnumResource, WNetGetLastError, WNetOpenEnum


WNetConnectionDialog

The WNetConnectionDialog function starts a general browsing dialog box for connecting to network resources.

DWORD WNetConnectionDialog(

HWND  hwnd,	// handle of window owning dialog box
DWORD  fdwResourceType	// resource type to allow connections to
);
Parameters

hwnd

Identifies the owning window.

fdwResourceType

Specifies the resource type to allow connections to. This parameter can be the following value:

Value	Meaning
RESOURCETYPE_DISK	Connects to disk resources.
Return Value

If the function succeeds, the return value is NO_ERROR. If the user cancels the dialog box, it is 0xFFFFFFFF.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_EXTENDED_ERROR	A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_INVALID_PASSWORD	The specified password is invalid.
ERROR_NO_NETWORK	No network is present.
ERROR_NOT_ENOUGH_MEMORY	There is insufficient memory to start the dialog box.
The function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by the GetLastError function.

Remarks

If the user chooses OK in the dialog box, the requested network connections will have been performed when WNetConnectionDialog returns.

If the function attempts to make a connection and the provider returns the message ERROR_INVALID_PASSWORD, Windows prompts the user to enter a password and uses the new password in another attempt to make the connection.

See Also

WNetAddConnection2, WNetCancelConnection2, WNetDisconnectDialog, WNetGetLastError


WNetDisconnectDialog

The WNetDisconnectDialog function starts a general browsing dialog box for disconnecting from network resources.

DWORD WNetDisconnectDialog(

HWND  hwnd,	// handle of window owning dialog box
DWORD  fdwResourceType	// resource type to disconnect from
);
Parameters

hwnd

Identifies the owning window.

fdwResourceType

Specifies the resource type to disconnect from. This parameter may be one of the following values:

Value	Meaning
RESOURCETYPE_DISK	Disconnects from disk resources.
RESOURCETYPE_PRINT	Disconnects from print resources.
Return Value

If the function succeeds, the return value is NO_ERROR. If the user cancels out of the dialog box, it is 0xFFFFFFFF.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_EXTENDED_ERROR	A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_NO_NETWORK	No network is present.
ERROR_NOT_ENOUGH_MEMORY	There is insufficient memory to start the dialog box.
The function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

Remarks

If the user chooses OK in the dialog box, the requested network disconnections will have been performed when WNetDisconnectDialog returns.

See Also

WNetAddConnection2, WNetCancelConnection2, WNetConnectionDialog, WNetGetLastError


WNetEnumResource

The WNetEnumResource function continues a network-resource enumeration started by the WNetOpenEnum function.

DWORD WNetEnumResource(

HANDLE  hEnum,	// handle of enumeration
LPDWORD  lpcEntries,	// address of entries to list
LPVOID  lpvBuffer,	// address of buffer for results
LPDWORD  lpcbBuffer	// address of buffer size variable
);
Parameters

hEnum

Identifies an enumeration instance. This handle must be returned by WNetOpenEnum.

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 this parameter contains the number of entries actually read.

lpvBuffer

Points to the buffer that receives the enumeration results, which are returned as an array of NETRESOURCE structures. The buffer is valid until the next call using the handle given by the hEnum parameter. The order of NETRESOURCE structures in the array is not predictable.

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 parameter receives the required size of the buffer.

Return Value

If the function succeeds, the return value is one of the following values:

Value	Meaning
NO_ERROR	The enumeration succeeded, and the buffer contains the requested data. The calling application can continue to call WNetEnumResource to complete the enumeration.
ERROR_NO_MORE_ITEMS	There are no more entries. The buffer contents are undefined.
If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_MORE_DATA	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. To get a description of the error, use the WNetGetLastError function.
The function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

Remarks

An application cannot set the 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 — 16 kilobytes (K) is typical — and use the value of lpcbBuffer for error detection.

See Also

NETRESOURCE, WNetCloseEnum, WNetGetLastError, WNetOpenEnum


WNetGetConnection

The WNetGetConnection function retrieves the name of the network resource associated with a local device.

DWORD WNetGetConnection(

LPTSTR  lpszLocalName,	// address of local name
LPTSTR  lpszRemoteName,	// address of buffer for remote name
LPDWORD  lpcchBuffer	// address of buffer size, in characters
);
Parameters

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 receives 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 parameter returns the required buffer size.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_BAD_DEVICE	The string pointed to by the lpszLocalName parameter 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 persistent connection.
ERROR_NO_NETWORK	No network is present.
ERROR_EXTENDED_ERROR	A network-specific error occurred. To get a description of the error, use the WNetGetLastError function.
ERROR_NO_NET_OR_BAD_PATH	None of the providers recognized this local name as having a connection. However, the network is not available for at least one provider to whom the connection may belong.
The WNetGetConnection function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

See Also

WNetAddConnection2, WNetAddConnection3, WNetGetLastError, WNetGetUser


WNetGetLastError

The WNetGetLastError function retrieves the most recent extended error code set by a Windows network function.

DWORD WNetGetLastError(

LPDWORD  lpdwErrorCode,	// address of error code
LPTSTR  lpszDescription,	// address of string describing error
DWORD  cchDescription,	// size of description buffer, in characters
LPTSTR  lpszName,	// address of buffer for provider name
DWORD  cchName	// size of provider name buffer
);
Parameters

lpdwErrorCode

Points to the variable that receives the error code reported by the network provider. The error code is specific to the network provider.

lpszDescription

Points to the buffer that receives 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 receives 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.

Return Value

If the function successfully obtains the last error reported by the provider, the return value is NO_ERROR. If the caller supplies an invalid buffer, it is ERROR_INVALID_ADDRESS.

Remarks

WNetGetLastError is used to obtain errors that are specific to a network provider. It should be used when a Windows network function (or the GetLastError function) returns ERROR_EXTENDED_ERROR. Like GetLastError, the function returns extended error information, which is maintained on a per-thread basis. Unlike GetLastError, the WNetGetLastError function can also return a string for reporting errors that are not described by any existing error code.

See Also

GetLastError


WNetGetResourceInformation

The WNetGetResourceInformation function retrieves enumeration information for a network resource. You typically use this function when the user specifies an object. Call this function in conjunction with WNetGetResourceParent to determine the placement and nature of the resource in the browse hierarchy. Unlike WNetGetResourceParent, WNetGetResourceInformation always tries to determine the network provider that owns the resource and the type of the resource, although it might not currently be accessible (or even exist if the type of the resource was specified by the caller).

DWORD WNetGetResourceInformation(

LPNETRESOURCE lpNetResource,	// specifies the network resource
LPVOID lpBuffer,	// pointer to a buffer for results
LPDWORD cbBuffer,	// size of the buffer
LPTSTR *lplpSystem	// pointer to a string in the buffer
);
Parameters

lpNetResource

Specifies the network resource for which the information is required. The lpRemoteName member of the NETRESOURCEstructure specifies the remote name of the network resource. The user typically provides this.

Determining the values of the lpProvider and especially the dwType members of the NETRESOURCE structure is a time-consuming operation. If the calling application has these values, it should fill them in. Otherwise, it should set them to NULL. All other members in the NETRESOURCE structure are ignored.

lpBuffer

Points to the buffer that receives the result. The first field in the buffer is a NETRESOURCE structure. The dwScope, lpRemoteName, lpProvider, dwType, and dwUsage members of the structure are returned; all other members are set to NULL.

The remote name pointed to by lpRemoteName is in the same syntax as that returned from an enumeration, so that the calling application can perform a case-sensitive string comparison to determine whether an enumerated resource is this resource.

The provider name pointed to by lpProvider is always returned when it is known to which network the resource belongs. If the resource cannot be found on any of the networks, then lpRemoteName is returned as NULL, and lpProvider can be non-NULL if a parent for the resource is known to be on one of the networks.

The dwScope member is returned as RESOURCE_CONTEXT if the network resource is part of the user's network context. Otherwise, it is returned as zero.cbBuffer

Specifies the size of the buffer passed to WNetGetResourceInformation. If the buffer is too small to receive even one entry, the function returns the required size of the buffer in this variable, as well the value WN_MORE_DATA.

lplpSystem

Points to a string in the buffer pointed to by lpBuffer that specifies the part of the resource that is accessed through system-resource type-specific functions rather than WNet functions.

For example, if the input remote resource name is "\\SERVER\SHARE\DIR", then lpRemoteName is returned pointing to "\\SERVER\SHARE" and lplpSystem points to "\DIR". Both strings are stored in the buffer pointed to by lpBuffer.

Return Value

The function returns one of the following values:

Value	Meaning
WN_BAD_NETNAME	The network resource specified by the lpRemoteName member of the NETRESOURCE structure does not exist for any network. If the lpProvider member of the NETRESOURCE structure is not NULL, then a parent of the specified network resource does exist and can be accessed by calls to WNetGetResourceParent.
WN_EXTENDED_ERROR	A network-specific error occurred. Call WNetGetLastError to obtain a description of the error.
WN_MORE_DATA	The buffer is too small for the information. In this case, the function returns the required size of the buffer in cbBuffer.
WN_NO_NETWORK	The network is not present.
WN_SUCCESS	The call is successful.
See Also


WNetGetResourceParent

WNetGetResourceParent lets you navigate up from a resource. It enables browsing to commence based on the name of a network resource. This function also allows navigating up from a browsed resource to find connectable resources.

You can call WNetGetResourceParent for names that were returned by WNetEnumResource. Unlike WNetGetResourceInformation, if the resource syntactically has a parent, the parent is returned by WNetGetResourceParent, whether or not the parent actually exists.

DWORD WNetGetResourceParent(

LPNETRESOURCE lpNetResource,	// specifies the network resource
LPVOID lpBuffer,	// pointer to a buffer for results
LPDWORD lpBufferSize,	// size, in bytes, of the buffer
);
Parameters

lpNetResource

Specifies the network resource for which the parent name is required. You can obtain the NETRESOURCEstructure by calling WNetEnumResource or by constructing it yourself. The lpRemoteName member of the structure specifies the remote name of the network resource.

If the calling application has the values of the lpProvider and dwType members of the NETRESOURCE structure (as it would from a call to WNetGetResourceInformation), it should fill them in. Otherwise, it should set the members to NULL. All other members in the NETRESOURCE structure are ignored.

lpBuffer

Points to the buffer that receives the result, which is a single NETRESOURCE structure for the parent resource. The lpRemoteName, lpProvider, dwType, and dwUsage members are returned; all other members are set to NULL.

The remote name pointed to by lpRemoteName is in the same syntax as that returned from an enumeration, so that the caller can perform a case-sensitive string comparison to determine whether an enumerated resource is this resource.

The provider name pointed to by lpProvider is returned only if it is known to which network the resource belongs. If several networks could own the resource, (as might be the case for a resource such as "\\SERVER"), then lpProvider will be set to NULL. If a resource has no parent on any of the networks, then lpRemoteName is returned as NULL. If it is known that a network owns a parent of the resource, but the resource itself is not valid, then lpProvider is returned as a non-null value, together with a return status of WN_BAD_NETNAME.

Note that if a network shows that the object is on the network, but has no parent (for example, a server that is not part of a workgroup), then WNetGetResourceParent might return with lpRemoteName and lpProvider both set to NULL.

The RESOURCEUSAGE_CONNECTABLE value in the dwUsage member does not indicate that the resource can currently be connected to, but that the resource is connectable when it is available on the network.

lpBufferSize

Specifies the size, in bytes, of the buffer passed to WNetGetResourceParent. If the buffer is too small to hold the NETRESOURCE information, the function returns the required size of the buffer in this variable, as well as the value WN_MORE_DATA.

Return Value

The function returns one of the following values:

Value	Meaning
WN_ACCESS_DENIED	The user is authenticated to the network, but does not have sufficient permissions (access rights).
WN_BAD_NETNAME	The name pointed to by the lpRemoteName is not a syntactically valid name for a remote resource for any network.
WN_BAD_PROVIDER	The name pointed to by the lpProvider member does not match any network provider.
WN_MORE_DATA	The buffer is too small for the information. In this case, the function returns the required size of the buffer in lpBufferSize.
WN_NOT_AUTHENTICATED	The caller does not have the necessary permissions to obtain the name of the parent.
WN_SUCCESS	The call is successful.
See Also


WNetGetUniversalName

The WNetGetUniversalName function takes a drive-based path for a network resource and obtains a data structure that contains a more universal form of the name.

DWORD WNetGetUniversalName(

LPCTSTR  lpLocalPath,	// address of drive-based path for a network resource
DWORD  dwInfoLevel,	// specifies form of universal name to be obtained
LPVOID  lpBuffer,	// address of buffer that receives universal name data structure
LPDWORD  lpBufferSize	// address of variable that specifies size of buffer
);
Parameters

lpLocalPath

Points to a null-terminated string that is a drive-based path for a network resource.

For example, if drive H has been mapped to a network drive share, and the network resource of interest is a file named SAMPLE.DOC in the directory \WIN32\EXAMPLES on that share, the drive-based path is H:\WIN32\EXAMPLES\SAMPLE.DOC.

dwInfoLevel

Specifies the type of data structure that the function will store in the buffer pointed to by lpBuffer. This parameter can be one of the following values:

Value	Meaning
UNIVERSAL_NAME_INFO_LEVEL	The function will store a UNIVERSAL_NAME_INFO data structure in the buffer.
REMOTE_NAME_INFO_LEVEL_	The function will store a REMOTE_NAME_INFO data structure in the buffer.
The UNIVERSAL_NAME_INFO data structure points to a Universal Naming Convention (UNC) name string.

The REMOTE_NAME_INFO data structure points to a UNC name string and two additional connection information strings.

lpBuffer

Points to a buffer that receives the type of data structure specified by the dwInfoLevel parameter.

lpBufferSize

Points to a variable that specifies the size in bytes of the buffer pointed to by lpBuffer.

If the function succeeds, it sets the variable pointed to by lpBufferSize to the size in bytes of the data structure stored in the buffer. If the function fails because the buffer is too small, indicated by the ERROR_MORE_DATA error code, it sets the variable pointed to by lpBufferSize to the required buffer size.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_BAD_DEVICE	The string pointed to by lpLocalPath is invalid.
ERROR_CONNECTION_UNAVAIL	There is no current connection to the remote device, but there is a remembered (persistent) connection to it.
ERROR_EXTENDED_ERROR	A network-specific error occurred. Use the WNetGetLastError function to obtain a description of the error.
ERROR_MORE_DATA	The buffer pointed to by lpBuffer is too small. The function sets the variable pointed to by lpBufferSize to the required buffer size.
ERROR_NOT_SUPPORTED	The dwInfoLevel parameter was set to UNIVERSAL_NAME_INFO_LEVEL, but the network provider does not support UNC  names. This function is not supported by any of the network providers.
ERROR_NO_NET_OR_BAD_PATH	None of the providers recognized this local name as having a connection. However, the network is not available for at least one provider to whom the connection may belong.
ERROR_NO_NETWORK	There is no network present.
ERROR_NOT_CONNECTED	The device specified by lpLocalPath is not redirected.
Remarks

A universal form of a local drive-based path identifies a network resource in an unambiguous, computer-independent manner. The name can then be passed to processes on other computers, allowing those processes to obtain access to the resource.

The WNetGetUniversalName function currently supports one universal name form: universal naming convention (UNC) names, which look like the following:

\\servername\sharename\path\file

Using the example from the preceding description of the lpLocalPath parameter, if the shared network drive is on a server named COOLSERVER, and the share name is HOTSHARE, the UNC name for the network resource whose drive-based name is H:\WIN32\EXAMPLES\SAMPLE.DOC would be

\\coolserver\hotshare\win32\examples\sample.doc

The UNIVERSAL_NAME_INFO data structure contains a pointer to a UNC name string. The REMOTE_NAME_INFO data structure contains a pointer to a UNC name string. It also includes pointers to two other useful strings. A process can pass the REMOTE_NAME_INFO structure's lpszConnectionInfo member into the WNetAddConnection2 function to connect a local device to the network resource, and then append the string pointed to by the lpszRemainingPath member to the local device string. The resulting string can be passed to Win32 functions that use a drive-based path.

See Also

REMOTE_NAME_INFO, UNIVERSAL_NAME_INFO, WNetAddConnection2, WNetGetLastError


WNetGetUser

The WNetGetUser function retrieves the current default user name or the user name used to establish a network connection.

DWORD WNetGetUser(

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
);
Parameters

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 this parameter is NULL, Windows returns the name of the current user for the process.

If this parameter 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 receives the null-terminated user name.

lpcchBuffer

Points to a variable that specifies the size, in characters, of the buffer pointed to by lpszUserName. If the call fails because the buffer is not big enough, this variable contains the required buffer size.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_NOT_CONNECTED	The device specified by 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. To get a description of the error, use the WNetGetLastError function.
ERROR_NO_NET_OR_BAD_PATH	None of the providers recognized this local name as having a connection. However, the network is not available for at least one provider to whom the connection may belong.
The function returns error codes for compatibility with Windows version 3.1. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

See Also

WNetGetConnection, WNetGetLastError


WNetOpenEnum

The WNetOpenEnum function starts an enumeration of network resources or existing connections.

DWORD WNetOpenEnum(

DWORD  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
);
Parameters

fdwScope

Specifies the scope of the enumeration. This parameter can be one of the following values:

Value	Meaning
RESOURCE_CONNECTED	All currently connected resources (the fdwUsage parameter 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
This parameter is ignored if the fdwScope parameter is not RESOURCE_GLOBALNET.

lpNetResource

Points to a NETRESOURCE structure specifying the container to enumerate.

If this parameter is NULL, the root of the network is assumed. Windows organizes a network as a hierarchy; the root is the topmost container in the network. For more information about the Windows network functions, see Network.

If this parameter is not NULL, it must point to a NETRESOURCE structure. This structure can be filled in by the application or be returned by a call to the WNetEnumResource function. The NETRESOURCE structure must specify a container resource; that is, the RESOURCEUSAGE_CONTAINER value must be specified in the dwUsage member.

To enumerate all network resources, an application can begin the enumeration by calling WNetOpenEnum with lpNetResource set to NULL and then use the returned handle with WNetEnumResource to enumerate resources. If one of the resources in the NETRESOURCE array returned by the WNetEnumResource function is a container resource, WNetOpenEnum can be used to open the resource for further enumeration.

If the fdwScope parameter is not RESOURCE_GLOBALNET, this parameter must be NULL.

lphEnum

Points to a variable filled with an enumeration handle that can be used in a subsequent call to WNetEnumResource.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is an error code. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

Value	Meaning
ERROR_NOT_CONTAINER	The lpNetResource parameter does not point to a container.
ERROR_INVALID_PARAMETER	Either the fdwScope or 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. To get a description of the error, use the WNetGetLastError function.
The function returns error codes for compatibility with Windows version 3.1. For compatibility with Windows NT, the function also sets the error code value returned by GetLastError.

Remarks

The WNetOpenEnum function is used to begin enumeration of the resources in a single container. The following examples show the hierarchical structure of a Microsoft LAN Manager network and a Novell Netware network:

LanMan (container, in this case the provider)

  ACCOUNTING (container, in this case the domain)

    \\ACCTSPAY (container, in this case the server)

      PAYFILES (disk)

      LASERJET (print)

Netware (container, in this case the provider)

  MARKETING (container, in this case the server)

    SYS (disk, first one on any Netware server)

    ANOTHERVOLUME (disk)

    LASERJET (print)

See Also

NETRESOURCE, WNetCloseEnum, WNetEnumResource, WNetGetLastError


WriteConsole

The WriteConsole function writes a character string to a console screen buffer beginning at the current cursor location.

BOOL WriteConsole(

HANDLE  hConsoleOutput,	// handle 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
);
Parameters

hConsoleOutput

Identifies the console screen buffer to be written 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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

WriteConsole writes characters to a console screen buffer. It behaves like the WriteFile function, except it can write in either Unicode (wide-character) or ANSI mode. To create an application that maintains a single set of sources compatible with both modes, use WriteConsole rather than WriteFile. Although WriteConsole can be used only with a console screen buffer handle, WriteFile can be used with other handles (such as files or pipes). WriteConsole fails if used with a standard handle that has been redirected to be something other than a console handle.

Although an application can use WriteConsole in ANSI mode to write ANSI characters, consoles do not support ANSI escape sequences. However, some Win32 functions provide equivalent functionality: for example, SetCursorPos, SetConsoleTextAttribute, and GetConsoleCursorInfo.

WriteConsole writes characters to the screen buffer at the current cursor position. The cursor position advances as characters are written. The SetConsoleCursorPosition function sets the current cursor position.

Characters are written using the foreground and background color attributes associated with the screen buffer. The SetConsoleTextAttribute function changes these colors. To determine the current color attributes and the current cursor position, use GetConsoleScreenBufferInfo.

All of the input modes that affect the behavior of WriteFile have the same effect on WriteConsole. To retrieve and set the output modes of a console screen buffer, use the GetConsoleMode and SetConsoleMode functions.

See Also

GetConsoleCursorInfo, GetConsoleMode, GetConsoleScreenBufferInfo, ReadConsole, SetConsoleCursorPosition, SetConsoleMode, SetConsoleTextAttribute, SetCursorPos, WriteFile


WriteConsoleInput

The WriteConsoleInput function writes data directly to the console input buffer.

BOOL WriteConsoleInput(

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
);
Parameters

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 be written.

lpcWritten

Points to a 32-bit variable that receives the number of input records actually written.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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

INPUT_RECORD, PeekConsoleInput, ReadConsoleInput


WriteConsoleOutput

The WriteConsoleOutput function writes character and color attribute data to a specified rectangular block of character cells in a console screen buffer. The data to be written is taken from a correspondingly sized rectangular block at a specified location in the source buffer.

BOOL WriteConsoleOutput(

HANDLE  hConsoleOutput,	// handle 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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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 be written to in the screen buffer. A rectangle of the same size is located with its upper-left cell at the coordinates of the 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 no data is 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 rectangle reflects the cells in the destination rectangle for which there existed a corresponding cell in the source buffer, because WriteConsoleOutput clips the dimensions of the destination rectangle to the boundaries of the screen buffer.

If the rectangle specified by 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

CHAR_INFO, COORD, GetConsoleScreenBufferInfo, ReadConsoleOutput, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, SMALL_RECT, WriteConsoleOutputAttribute, WriteConsoleOutputCharacter


WriteConsoleOutputAttribute

The WriteConsoleOutputAttribute function copies a number of foreground and background color attributes to consecutive cells of a console screen buffer, beginning at a specified location.

BOOL WriteConsoleOutputAttribute(

HANDLE  hConsoleOutput,	// handle 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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the number of attributes to be written to extends beyond the end of the specified row in the screen buffer, attributes are written to the next row. If the number of attributes to be written to extends beyond the end of the screen buffer, the attributes are written up to the end of the screen buffer.

The character values at the positions written to are not changed.

Each attribute specifies the foreground (text) and background colors in which that character cell is drawn. The attribute values are some combination of the following values: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces red text on a white background:

FOREGROUND_RED | BACKGROUND_RED | BACKGROUND_GREEN | BACKGROUND_BLUE

See Also

ReadConsoleOutput, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, WriteConsoleOutput, WriteConsoleOutputCharacter


WriteConsoleOutputCharacter

The WriteConsoleOutputCharacter function copies a number of characters to consecutive cells of a console screen buffer, beginning at a specified location.

BOOL WriteConsoleOutputCharacter(

HANDLE  hConsoleOutput,	// handle 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
);
Parameters

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 32-bit variable that receives the number of characters actually written.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If the number of characters to be written to extends beyond the end of the specified row in the screen buffer, characters are written to the next row. If the number of characters to be written to extends beyond the end of the screen buffer, characters are written up to the end of the screen buffer.

The attribute values at the positions written to are not changed.

See Also

ReadConsoleOutput, ReadConsoleOutputAttribute, ReadConsoleOutputCharacter, WriteConsoleOutput, WriteConsoleOutputAttribute


WriteFile

The WriteFile function writes data to a file and is designed for both synchronous and asynchronous operation. The function starts writing data to the file at the position indicated by the file pointer. After the write operation has been completed, the file pointer is adjusted by the number of bytes actually written, except when the file is opened with FILE_FLAG_OVERLAPPED. If the file handle was created for overlapped input and output (I/O), the application must adjust the position of the file pointer after the write operation is finished.

BOOL WriteFile(

HANDLE  hFile,	// handle of 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
);
Parameters

hFile

Identifies the file to be written to. 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.

Named pipe write operations across a network are limited to 65535 bytes.

lpNumberOfBytesWritten

Points to the number of bytes written by this function call. WriteFile sets this value to zero before doing any work or error checking.

lpOverlapped

Points to an OVERLAPPED structure. This structure is required if hFile was opened with FILE_FLAG_OVERLAPPED.

This parameter should not be NULL if hFile was opened with FILE_FLAG_OVERLAPPED. It should 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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

If part of the file is locked by another process and the write operation overlaps the locked portion, this function fails.

Applications must not read from nor write to the input buffer that a read operation is using until the read operation completes. A premature access to the input buffer may lead to corruption of the data read into that buffer.

Characters can be written to the screen buffer using WriteFile with a handle to console output. The exact behavior of the function is determined by the console mode. The data is written to the current cursor position. The cursor position is updated after the write operation.

Unlike the MS-DOS operating system, Windows NT interprets zero bytes to write as specifying a null write operation and WriteFile does not truncate or extend the file. To truncate or extend a file, use the SetEndOfFile function.

When writing to a nonblocking, byte-mode pipe handle with insufficient buffer space, WriteFile returns TRUE with *lpNumberOfBytesWritten < nNumberOfBytesToWrite.

When an application uses the WriteFile function to write to a pipe, the write operation may not finish if the pipe buffer is full. The write operation is completed when a read operation (using the ReadFile function) makes more buffer space available.

If the anonymous read pipe handle has been closed and WriteFile attempts to write using the corresponding anonymous write pipe handle, the function returns FALSE and GetLastError returns ERROR_BROKEN_PIPE.

The WriteFile function may fail with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY whenever there are too many outstanding asynchronous I/O requests.

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, GetLastError, GetOverlappedResult, OVERLAPPED, ReadFile, SetEndOfFile, WriteFileEx


WriteFileEx

The WriteFileEx function writes data to a file. It is designed solely for asynchronous operation, unlike WriteFile, which is designed for both synchronous and asynchronous operation.

WriteFileEx reports its completion status asynchronously, calling a specified completion routine when writing is completed and the calling thread is in an alertable wait state.

BOOL WriteFileEx(

HANDLE  hFile;	// handle to output file
LPCVOID  lpBuffer;	// pointer to input buffer
DWORD  nNumberOfBytesToWrite;	// number of bytes to write
LPOVERLAPPED  lpOverlapped;	// pointer to async. i/o data
LPOVERLAPPED_COMPLETION_ROUTINE  lpCompletionRoutine;	// ptr. to completion routine
);
Parameters

hFile

An open handle that specifies the file entity to be written to. This file handle must have been created with the FILE_FLAG_OVERLAPPED flag and with GENERIC_WRITE access to the file.

Windows NT : hFile can be any handle opened with the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept functions.

Windows 95 : hFile can be a communications resource, mailslot, or named pipe handle opened with the FILE_FLAG_OVERLAPPED flag by CreateFile, or a socket handle returned by the socket or accept functions. Windows 95 does not support asynchronous operations on disk files.

lpBuffer

Points to the buffer containing the data to be written to the file.

This buffer must remain valid for the duration of the write operation. The caller must not use this buffer until the write operation is completed.

nNumberOfBytesToWrite

Specifies the number of bytes to write to the file.

If nNumberOfBtyesToWrite is zero, this function does nothing; in particular, it does not truncate the file. For additional discussion, see the following Remarks section.

lpOverlapped

Points to an OVERLAPPED data structure that supplies data to be used during the overlapped (asynchronous) write operation.

For files that support byte offsets, you must specify a byte offset at which to start writing to the file. You specify this offset by setting the Offset and OffsetHigh members of the OVERLAPPED structure. For files that do not support byte offsets — named pipes, for example — you must set Offset and OffsetHigh to zero, or WriteFileEx fails.

The WriteFileEx function ignores the OVERLAPPED structure's hEvent member. An application is free to use that member for its own purposes in the context of a WriteFileEx call. WriteFileEx signals completion of its writing operation by calling, or queueing a call to, the completion routine pointed to by lpCompletionRoutine, so it does not need an event handle.

The WriteFileEx function does use the Internal and InternalHigh members of the OVERLAPPED structure. You should not change the value of these members.

The OVERLAPPED data structure must remain valid for the duration of the write operation. It should not be a variable that can go out of scope while the write operation is pending completion.

lpCompletionRoutine

Points to a completion routine to be called when the write operation has been completed and the calling thread is in an alertable wait state. For more information about this completion routine, see FileIOCompletionRoutine.

Return Value

If the function succeeds, the return value is TRUE.

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

If the WriteFileEx function succeeds, the calling thread has an asynchronous I/O (input/output) operation pending: the overlapped write operation to the file. When this I/O operation finishes, and the calling thread is blocked in an alertable wait state, the operating system calls the function pointed to by lpCompletionRoutine, and the wait completes with a return code of WAIT_IO_COMPLETION.

If the function succeeds and the file-writing operation finishes, but the calling thread is not in an alertable wait state, the system queues the call to *lpCompletionRoutine, holding the call until the calling thread enters an alertable wait state.

Remarks

If part of the output file is locked by another process, and the specified write operation overlaps the locked portion, the WriteFileEx function fails.

Applications must not read from nor write to the input buffer that a read operation is using until the read operation completes. A premature access to the input buffer may lead to corruption of the data read into that buffer.

The WriteFileEx function may fail, returning the messages ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY if there are too many outstanding asynchronous I/O requests.

If hFile is a handle to a named pipe, or other file entity that doesn't support byte offsets, the Offset and OffsetHigh members of the OVERLAPPED structure pointed to by lpOverlapped must be zero, or the WriteFileEx function fails.

An application uses the WaitForSingleObjectEx, WaitForMultipleObjectsEx, and SleepEx functions to enter an alertable wait state. Refer to those functions for more information about alertable wait states and overlapped input/output operations.

See Also

CreateFile, FileIOCompletionRoutine, OVERLAPPED, ReadFileEx, SetEndOfFile, SleepEx, WaitForMultipleObjectsEx, WaitForSingleObjectEx, WriteFile


WritePrinter

The WritePrinter function informs the print spooler that data should be written to the specified printer.

BOOL WritePrinter(

HANDLE  hPrinter,	// handle 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
);
Parameters

hPrinter

Identifies the printer.

pBuf

Points to an array of bytes that contains the data that should be written to the printer.

cbBuf

Specifies the size, in bytes, of the array.

lpdwWritten

Points to a value that specifies the number of bytes of data that were written to the printer.

Return Value

If the function succeeds, the return value is TRUE.

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

See Also

OpenPrinter


WritePrivateProfileSection

The WritePrivateProfileSection function replaces the keys and values under the specified section in an initialization file.

This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

BOOL WritePrivateProfileSection(

LPCTSTR  lpszSection,	// address of string with section name
LPCTSTR  lpszKeysAndValues,	// address of string with data
LPCTSTR  lpszFile	// address of string with filename
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

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

Windows 95

Windows 95 keeps a cached version of WIN.INI to improve performance. If all three parameters are NULL, the function flushes the cache. The function always returns FALSE after flushing the cache, regardless of whether the flush succeeds or fails.

Windows NT

Windows NT maps most .INI file references to the registry, using the mapping defined under the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

This mapping is likely if an application modifies system-component initialization files, such as as CONTROL.INI, SYSTEM.INI, and WINFILE.INI. In this case, the WritePrivateProfileSection function writes information to the registry, not to the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

GetPrivateProfileSection, RegCreateKeyEx, RegSetValueEx, WriteProfileSection


WritePrivateProfileString

The WritePrivateProfileString function copies a string into the specified section of the specified initialization file.

This function is provided for compatibility with 16-bit Windows-based applications. WIn32-based applications should store initialization information in the registry.

BOOL WritePrivateProfileString(

LPCTSTR  lpszSection,	// address of section name
LPCTSTR  lpszKey,	// address of key name
LPCTSTR  lpszString,	// address of string to add
LPCTSTR  lpszFile	// address of initialization filename
);
Parameters

lpszSection

Points to a null-terminated string containing the name of the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case-independent; the string can be any combination of uppercase and lowercase letters.

lpszKey

Points to the null-terminated string containing the name of the key to be associated with a string. If the key does not exist in the specified section, it is created. If this parameter is NULL, the entire section, including all 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.

Return Value

If the function successfully copies the string to the initialization file, the return value is TRUE.

If the function fails, or if it flushes the cached version of the most recently accessed initialization file, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

Windows 95

Windows 95 keeps a cached version of WIN.INI to improve performance. If all three parameters are NULL, the function flushes the cache. The function always returns FALSE after flushing the cache, regardless of whether the flush succeeds or fails.

A section in the initialization file must have the following form:

[section]
key=string
      .
      .
      .

If the 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.

Windows NT

Windows NT maps most .INI file references to the registry, using the mapping defined under the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

Windows NT keeps a cache for the IniFleMapping registry key. Calling WritePrivateProfileString with the value of all arguments set to NULL will cause Windows NT to refresh its cache of the IniFileMappingKey for the specified .INI file.

An application using the WritePrivateProfileString function to enter .INI file information into the registry should follow these guidelines:

•	Ensure that no .INI file of the specified name exists on the system.

•	Ensure that there is a key entry in the registry that specifies the .INI file. This entry should be under the path HKEY_LOCAL_MACHINE\SOFTWARE \Microsoft\Windows NT\CurrentVersion\IniFileMapping.

•	Specify a value for that .INI file key entry that specifies a section. That is to say, an application must specify a section name, as it would appear within an .INI file or registry entry. Here is an example: [My Section].

•	For system files, specify SYS for an added value.

•	For application files, specify USR within the added value. Here is an example: "My Section: USR: App Name\Section". And, since USR indicates a mapping under HKEY_CURRENT_USER, the application should also create a key under HKEY_CURRENT_USER that specifies the application name listed in the added value. For the example just given, that would be "App Name".

•	After following the preceding steps, an application setup program should call WritePrivateProfileStringW with the first three parameters set to NULL, and the fourth parameter set to the INI filename. For example:

WritePrivateProfileStringW( NULL, NULL, NULL, "appname.ini" );

Such a call causes the mapping of an .INI file to the registry to take effect before the next system reboot. The operating system re-reads the mapping information into shared memory. A user will not have to reboot their computer after installing an application in order to have future invocations of the application see the mapping of the .INI file to the registry.

The following sample code illustrates the preceding guidelines and is based on several assumptions:

•	There is an application named "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.

•	The user will not have to reboot the system in order to have future invocations of the application see the mapping of the .INI file to the registry.

Here is the sample code :

// include files

#include <stdio.h>

#include <windows.h>

// a main function

main()

{

  // local variables

  CHAR inBuf[80];

  HKEY  hKey1, hKey2;

  DWORD  dwDisposition;

  LONG   lRetCode;

  // try to create the .INI file key

  lRetCode = RegCreateKeyEx ( HKEY_LOCAL_MACHINE,

                              "SOFTWARE\\Microsoft\\Windows NT

                               \\CurrentVersion\\IniFileMapping\\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) ;

    }

  // force the operating system to re-read the mapping into shared memory

  //    so that future invocations of the application will see it

  //    without the user having to reboot the system

  WritePrivateProfileStringW( NULL, NULL, NULL, "foobar.ini" );

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


WritePrivateProfileStruct  (preliminaryWindows NT)
WritePrivateProfileStruct  (preliminary−Windows NT)

The WritePrivateProfileStruct function copies data into the specified key in the given section of an initialization file. As it copies the data, the function calculates a checksum and appends it to the end of the data. The GetPrivateProfileStruct function uses the checksum to ensure the integrity of the data. This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

BOOL WritePrivateProfileStruct(

LPCTSTR  lpszSection,	// address of section name
LPCTSTR  lpszKey,	// address of key name
LPVOID  lpvStruct,	// address of buffer that contains data to add
UINT  uSizeStruct,	// size, in bytes, of the buffer
LPCTSTR  lpszFile	// address of initialization filename
);
Parameters

lpszSection

Points to a null-terminated string containing the name of the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case independent, the string can be any combination of uppercase and lowercase letters.

lpszKey

Points to the null-terminated string containing the name of the key to be associated with a string. If the key does not exist in the specified section, it is created. If this parameter is NULL, the entire section, including all keys and entries within the section, is deleted.

lpvStruct

Points to a buffer that contains the data to copy. If this parameter is NULL, the given key is deleted.

uSizeStruct

Specifies the size, in bytes, of the buffer pointed to by the lpvStruct parameter.

lpszFile

Points to a null-terminated string that names the initialization file. If this parameter is NULL, the given information is copied into the WIN.INI file.

Return Value

If the function successfully copies the string to the initialization file, the return value is TRUE.

If the function fails, or if it flushes the cached version of the most recently accessed initialization file, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

Windows 95 keeps a cached version of WIN.INI to improve performance. If all three parameters are NULL, the function flushes the cache. The function always returns FALSE after flushing the cache, regardless of whether the flush succeeds or fails.

A section in the initialization file must have the following form:

[section]
key=string
      .
      .
      .

If the 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.

See Also

GetPrivateProfileString, WriteProfileString


WriteProcessMemory

The WriteProcessMemory function writes memory in a specified process. The entire area to be written to must be accessible, or the operation fails.

BOOL WriteProcessMemory(

HANDLE  hProcess,	// handle 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
);
Parameters

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 address space of the specified process.

cbWrite

Specifies the requested number of bytes to write into the specified process.

lpNumberOfBytesWritten

Points to the actual number of bytes transferred into the specified process. This parameter is optional. If lpNumberOfBytesWritten is NULL, the parameter is ignored.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError. The function will fail if the requested write operation crosses into an area of the process that is inaccessible.

Remarks

WriteProcessMemory copies the data from the specified buffer in the current process to the address range of the specified process. Any process that has a handle with PROCESS_VM_WRITE and PROCESS_VM_OPERATION access to the process to be written to can call the function. The process whose address space is being written to is typically, but not necessarily, being debugged.

The entire area to be written to must be accessible. If it is not, the function fails as noted previously.

See Also

ReadProcessMemory


WriteProfileSection

The WriteProfileSection function replaces the contents of the specified section in the WIN.INI file with the specified keys and values.

This function is provided for compatibility with 16-bit Windows applications. Win32-based applications should store initialization information in the registry.

BOOL WriteProfileSection(

LPCTSTR  lpszSection,	// address of section name
LPCTSTR  lpszKeysAndValues	// address of buffer with data
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

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

Remarks

Windows 95

If there is no section in WIN.INI that matches the specified section name, WriteProfileSection creates the section at the end of the file and initializes the new section with the key name and value pairs specified in the lpszKeysAndValues parameter.

Keys and values in the lpszKeysAndValues buffer consist of one or more null-terminated strings, followed by a final null character. Each string has the following form:

key=string

The WriteProfileSection function is not case-sensitive; the strings can be a combination of uppercase and lowercase letters.

WriteProfileSection deletes the existing keys and values for the named section and inserts the key names and values in the buffer pointed to by 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.

Windows NT

Windows NT maps most .INI file references to the registry, using the mapping defined under the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

When the operation has been mapped, the WriteProfileSection function writes information to the registry, not to the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

GetProfileSection, WritePrivateProfileSection


WriteProfileString

The WriteProfileString function copies a string into the specified section of the WIN.INI file.

This function is provided for compatibility with 16-bit Windows-based applications. Win32-based applications should store initialization information in the registry.

BOOL WriteProfileString(

LPCTSTR  lpszSection,	// address of section name
LPCTSTR  lpszKey,	// address of key name
LPCTSTR  lpszString	// address of string to write
);
Parameters

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.

Return Value

If the function successfully copies the string to the WIN.INI file, the return value is TRUE.

If the function fails, or if it flushes the cached version of WIN.INI, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

Windows 95:

Windows 95 keeps a cached version of WIN.INI to improve performance. If all three parameters are NULL, the function flushes the cache. The function always returns FALSE after flushing the cache, regardless of whether the flush succeeds or fails.

A section in the WIN.INI file must have the following form:

[section]
key=string
    .
    .
    .

Windows NT

Windows NT maps most .INI file references to the registry, using the mapping defined under the following registry key:

HKEY_LOCAL_MACHINE\Software\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

When the operation has been mapped, the WriteProfileString function writes information to the registry, not to the initialization file; the change in the storage location has no effect on the function's behavior.

See Also

GetProfileString, WritePrivateProfileString


WriteTapemark

The WriteTapemark function writes a specified number of filemarks, setmarks, short filemarks, or long filemarks to a tape device. These tapemarks divide a tape partition into smaller areas.

DWORD WriteTapemark(

HANDLE  hDevice,	// handle of open device
DWORD  dwTapemarkType,	// type of tapemarks to write
DWORD  dwTapemarkCount,	// number of tapemarks to write
BOOL  bImmediate	// return after write begins
);
Parameters

hDevice

Identifies the device on which to write tapemarks. This handle is created by using the CreateFile function.

dwTapemarkType

Specifies the type of tapemarks to write. This parameter can be one of the following values:

Value	Description
TAPE_FILEMARKS	Writes the number of filemarks specified by the dwTapemarkCount parameter.
TAPE_LONG_FILEMARKS	Writes the number of long filemarks specified by dwTapemarkCount.
TAPE_SETMARKS	Writes the number of setmarks specified by dwTapemarkCount.
TAPE_SHORT_FILEMARKS	Writes the number of short filemarks specified by dwTapemarkCount.
dwTapemarkCount

Specifies the number of tapemarks to write.

bImmediate

Specifies whether to return as soon as the operation begins. If this parameter is TRUE, the function returns immediately; if it is FALSE, the function does not return until the operation has been completed.

Return Value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes:

Error	Description
ERROR_BEGINNING_OF_MEDIA	An attempt to access data before the beginning-of-medium marker failed.
ERROR_BUS_RESET	A reset condition was detected on the bus.
ERROR_END_OF_MEDIA	The end-of-tape marker was reached during an operation.
ERROR_FILEMARK_DETECTED	A filemark was reached during an operation.
ERROR_SETMARK_DETECTED	A setmark was reached during an operation.
ERROR_NO_DATA_DETECTED	The end-of-data marker was reached during an operation.
ERROR_PARTITION_FAILURE	The tape could not be partitioned.
ERROR_INVALID_BLOCK_LENGTH	The block size is incorrect on a new tape in a multivolume partition.
ERROR_DEVICE_NOT_PARTITIONED	The partition information could not be found when a tape was being loaded.
ERROR_MEDIA_CHANGED	The tape that was in the drive has been replaced or removed.
ERROR_NO_MEDIA_IN_DRIVE	There is no media in the drive.
ERROR_NOT_SUPPORTED	The tape driver does not support a requested function.
ERROR_UNABLE_TO_LOCK_MEDIA	An attempt to lock the ejection mechanism failed.
ERROR_UNABLE_TO_UNLOAD_MEDIA	An attempt to unload the tape failed.
ERROR_WRITE_PROTECT	The media is write protected.
Remarks

Filemarks, setmarks, short filemarks, and long filemarks are special recorded elements that denote the linear organization of the tape. None of these marks contain user data. Filemarks are the most general marks; setmarks provide a hierarchy not available with filemarks.

A short filemark contains a short erase gap that cannot be overwritten unless the write operation is performed from the beginning of the partition or from an earlier long filemark.

A long filemark contains a long erase gap that allows an application to position the tape at the beginning of the filemark and to overwrite the filemark and the erase gap.

See Also

CreateFile


WSAAsyncGetHostByAddr

The Windows Sockets WSAAsyncGetHostByAddr function gets host information corresponding to an address in an asynchronous fashion.

HANDLE WSAAsyncGetHostByAddr (

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

hWnd

The handle of the window that should receive a message when the asynchronous request completes.

wMsg

The message to be received when the asynchronous request completes.

addr

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

len

The length of the address, which must be 4 for PF_INET.

type

The type of the address, which must be PF_INET.

buf

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

buflen

The size of data area buf above.

Return Value

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

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

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

Error Codes

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

WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAENOBUFS	Buffer space is insufficient or unavailable.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
Remarks

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

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

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

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

#define WSAGETASYNCERROR(lParam)  HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)  LOWORD(lParam)

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

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

Notes for Windows Sockets Suppliers

It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage operation fails, the Windows Sockets implementation must repost that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

See Also

gethostbyaddr, PostMessage, WSACancelAsyncRequest, WSAStartup


WSAAsyncGetHostByName

The Windows Sockets WSAAsyncGetHostByName function gets host information corresponding to a host name in an asynchronous fashion.

HANDLE WSAAsyncGetHostByName (

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

hWnd

The handle of the window that should receive a message when the asynchronous request completes.

wMsg

The message to be received when the asynchronous request completes.

name

A pointer to the name of the host.

buf

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

buflen

The size of data area buf above.

Return Value

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

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

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

Error Codes

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

WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAENOBUFS	Buffer space is insufficien or unavailable.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
Remarks

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

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

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

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

#define WSAGETASYNCERROR(lParam)   HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)  LOWORD(lParam)

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

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

Notes for Windows Sockets Suppliers

It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage operation fails, the Windows Sockets implementation must repost that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

See Also

gethostbyname, PostMessage, WSACancelAsyncRequest, WSAStartup


WSAAsyncGetProtoByName

The Windows Sockets WSAAsyncGetProtoByName function gets protocol information corresponding to a protocol name in an asynchronous fashion.

HANDLE WSAAsyncGetProtoByName (

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

hWnd

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

wMsg

The message to be received when the asynchronous request completes.

name

A pointer to the protocol name to be resolved.

buf

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

buflen

The size of data area buf above.

Return Value

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

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

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

Error Codes

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

WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAENOBUFS	Buffer space is insufficient or unavailable.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
Remarks

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

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

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

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

#define WSAGETASYNCERROR(lParam)   HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)  LOWORD(lParam)

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

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

Notes for Windows Sockets Suppliers

It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage operation fails, the Windows Sockets implementation must repost that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

See Also

getprotobyname, PostMessage, WSACancelAsyncRequest, WSAStartup


WSAAsyncGetProtoByNumber

The Windows Sockets WSAAsyncGetProtoByNumber function gets protocol information corresponding to a protocol number in an asynchronous fashion.

HANDLE WSAAsyncGetProtoByNumber (

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

hWnd

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

wMsg

The message to be received when the asynchronous request completes.

number

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

buf

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

buflen

The size of data area buf above.

Return Value

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

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

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

Error Codes

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

WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAENOBUFS	Buffer space is insufficient or unavailable.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
Remarks

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

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

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

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

#define WSAGETASYNCERROR(lParam)   HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)  LOWORD(lParam)

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

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

Notes for Windows Sockets Suppliers

It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage operation fails, the Windows Sockets implementation must repost that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

See Also

getprotobynumber, PostMessage, WSACancelAsyncRequest, WSAStartup


WSAAsyncGetServByName

The Windows Sockets WSAAsyncGetServByName function gets service information corresponding to a service name and port in an asynchronous fashion.

HANDLE WSAAsyncGetServByName (

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

hWnd

The handle of the window that should receive a message when the asynchronous request completes.

wMsg

The message to be received when the asynchronous request completes.

name

A pointer to a service name.

proto

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

buf

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

buflen

The size of data area buf  above.

Return Value

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

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

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

Error Codes

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

WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAENOBUFS	Buffer space is insufficient or unavailable.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
Remarks

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

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

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

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

#define WSAGETASYNCERROR(lParam)   HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)  LOWORD(lParam)

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

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

Notes for Windows Sockets Suppliers

It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage operation fails, the Windows Sockets implementation must repost that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

See Also

getservbyname, PostMessage, WSACancelAsyncRequest, WSAStartup


WSAAsyncGetServByPort

The Windows Sockets WSAAsyncGetServByPort function gets service information corresponding to a port and protocol in an asynchronous fashion.

HANDLE WSAAsyncGetServByPort (

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

hWnd

The handle of the window that should receive a message when the asynchronous request completes.

wMsg

The message to be received when the asynchronous request completes.

port

The port for the service, in network byte order.

proto

A pointer to a protocol name. This may be NULL, in which case WSAAsyncGetServByPort will search for the first service entry that matches the specified port. Otherwise, WSAAsyncGetServByPort matches both port and proto.

buf

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

buflen

The size of data area buf  above.

Return Value

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

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

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

Error Codes

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

WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAENOBUFS	Buffer space is insufficient or unavailable.
WSAHOST_NOT_FOUND	Authoritative Answer Host not found.
WSATRY_AGAIN	Non-Authoritative Host not found, or SERVERFAIL.
WSANO_RECOVERY	Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Valid name, no data record of requested type.
The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEWOULDBLOCK	The asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.
Remarks

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

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

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

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

#define WSAGETASYNCERROR(lParam)   HIWORD(lParam)

#define WSAGETASYNCBUFLEN(lParam)  LOWORD(lParam)

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

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

Notes for Windows Sockets Suppliers

It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage operation fails, the Windows Sockets implementation must repost that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.

See Also

getservbyport, PostMessage, WSACancelAsyncRequest, WSAStartup


WSAAsyncSelect

The Windows Sockets WSAAsyncSelect function requests event notification for a socket.

int WSAAsyncSelect (

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

s

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

hWnd

A handle identifying the window that should receive a message when a network event occurs.

wMsg

The message to be received when a network event occurs.

lEvent

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

Return Value

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

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINVAL	Indicates that one of the specified parameters was invalid.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
	Additional error codes may be set when an application window receives a message. This error code is extracted from the lParam in the reply message using the WSAGETSELECTERROR macro. Possible error codes for each network event are listed following:
Event: FD_CONNECT

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

Error Code	Meaning
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAECONNRESET	The connection was reset by the remote side.
WSAECONNABORTED	The connection was aborted due to timeout or other failure.
Event: FD_READ, Event: FD_WRITE, Event: FD_OOB, Event: FD_ACCEPT

Error Code	Meaning
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
Notes for Windows Sockets Suppliers

It is the responsibility of the Windows Sockets Supplier to ensure that messages are successfully posted to the application. If a PostMessage operation fails, the Windows Sockets implementation must repost that message as long as the window exists.

Windows Sockets suppliers should use the WSAMAKESELECTREPLY macro when constructing the lParam in the message.

When a socket is closed, the Windows Sockets supplier should purge any messages remaining for posting to the application window. However, the application must be prepared to receive, and discard, any messages that may have been posted prior to the closesocket.

Remarks

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

This function automatically sets socket s to nonblocking mode.

The lEvent parameter is constructed by using a bitwise OR operation with any of the values specified in the following list.

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

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

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

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

rc = WSAAsyncSelect(s, hWnd, wMsg2, FD_WRITE);

To cancel all notification  — that is, to indicate that the Windows Sockets implementation should send no further messages related to network events on the socket − lEvent should be set to zero.

rc = WSAAsyncSelect(s, hWnd, 0, 0);

Although in this instance WSAAsyncSelect immediately disables event message posting for the socket, it is possible that messages may be waiting in the application's message queue. The application must therefore be prepared to receive network event messages even after cancellation. Closing a socket with closesocket also cancels WSAAsyncSelect message sending, but the same caveat about messages in the queue prior to the closesocket still applies.

Since an accepted socket has the same properties as the listening socket used to accept it, any WSAAsyncSelect events set for the listening socket apply to the accepted socket. For example, if a listening socket has WSAAsyncSelect events FD_ACCEPT, FD_READ, and FD_WRITE, then any socket accepted on that listening socket will also have FD_ACCEPT, FD_READ, and FD_WRITE events with the same wMsg value used for messages. If a different wMsg or events are desired, the application should call WSAAsyncSelect, passing the accepted socket and the desired new information. (Note that there is a timing window between the accept call and the call to WSAAsyncSelect to change the events or wMsg. An application that desires a different wMsg for the listening and accepted sockets should ask for only FD_ACCEPT events on the listening socket, then set appropriate events after the accept. Since FD_ACCEPT is never sent for a connected socket and FD_READ, FD_WRITE, FD_OOB, and FD_CLOSE are never sent for listening sockets, this will not impose difficulties.)

When one of the nominated network events occurs on the specified socket s, the application's window hWnd receives message wMsg. The wParam argument identifies the socket on which a network event has occurred. The low word of lParam specifies the network event that has occurred. The high word of lParam contains any error code. The error code be any error as defined in WINSOCK.H.

The error and event codes may be extracted from the lParam using the macros WSAGETSELECTERROR and WSAGETSELECTEVENT, defined in WINSOCK.H as:

#define WSAGETSELECTERROR(lParam)  HIWORD(lParam)

#define WSAGETSELECTEVENT(lParam)  LOWORD(lParam)

The use of these macros will maximize the portability of the source code for the application.

The possible network event codes that may be returned are as follows:

Value	Meaning
FD_READ	Socket s is ready for reading.
FD_WRITE	Socket s is ready for writing.
FD_OOB	Out-of-band data is ready for reading on socket s.
FD_ACCEPT	Socket s is ready for accepting a new incoming connection.
FD_CONNECT	Connection on socket s completed.
FD_CLOSE	Connection identified by socket s has been closed.
Although WSAAsyncSelect can be called with interest in multiple events, the application window will receive a single message for each network event.

As in the case of the select function, WSAAsyncSelect will frequently be used to determine when a data transfer operation (send or recv) can be issued with the expectation of immediate success. Nevertheless, a robust application must be prepared for the possibility that it may receive a message and issue a Windows Sockets function call which returns WSAEWOULDBLOCK immediately. For example, the following sequence of events is possible:

1.	Data arrives on socket s; Windows Sockets posts WSAAsyncSelect message.

2.	Application processes some other message.

3.	While processing, application issues an ioctlsocket(s, FIONREAD...) and notices that there is data ready to be read.

4.	Application issues a recv(s,...) to read the data.

5.	Application loops to process next message, eventually reaching the WSAAsyncSelect message, indicating that data is ready to read.

6.	Application issues recv(s,...), which fails with the error WSAEWOULDBLOCK.

Other sequences are possible.

The Windows Sockets DLL will not continually flood an application with messages for a particular network event. Having successfully posted notification of a particular event to an application window, no further message(s) for that network event will be posted to the application window until the application makes the function call which implicitly reenables notification of that network event.

Event	Reenabling function
FD_READ	recv or recvfrom
FD_WRITE	send or sendto
FD_OOB	recv
FD_ACCEPT	accept
FD_CONNECT	NONE
FD_CLOSE	NONE
Any call to the reenabling routine, even one that fails, results in reenabling of message posting for the relevant event.

For FD_READ, FD_OOB, and FD_ACCEPT events, message posting is "level-triggered." This means that if the reenabling routine is called and the relevant event is still valid after the call, a WSAAsyncSelect message is posted to the application. This allows an application to be event-driven and not concern itself with the amount of data that arrives at any one time. Consider the following sequence:

1.	Windows Sockets DLL receives 100 bytes of data on socket s and posts an FD_READ message.

2.	The application issues recv( s, buffptr, 50, 0) to read 50 bytes.

3.	The Windows Sockets DLL posts another FD_READ message, since there is still data to be read.

With these semantics, an application need not read all available data in response to an FD_READ message — a single recv in response to each FD_READ message is appropriate. If an application issues multiple recv calls in response to a single FD_READ, it may receive multiple FD_READ messages. Such an application may need to disable FD_READ messages before starting the recv calls by calling WSAAsyncSelect with the FD_READ event not set.

If an event is true when the application initially calls WSAAsyncSelect or when the reenabling function is called, then a message is posted as appropriate. For example, if an application calls listen, a connect attempt is made, then the application calls WSAAsyncSelect specifying FD_ACCEPT, the Windows Sockets implementation posts an FD_ACCEPT message immediately.

The FD_WRITE event is handled slightly differently. An FD_WRITE message is posted when a socket is first connected with connect or accepted with accept, and then after a send or sendto fails with WSAEWOULDBLOCK and buffer space becomes available. Therefore, an application can assume that sends are possible starting from the first FD_WRITE message and lasting until a send returns WSAEWOULDBLOCK. After such a failure, the application will be notified that sends are again possible with an FD_WRITE message.

The FD_OOB event is used only when a socket is configured to receive out-of-band data separately. If the socket is configured to receive out-of-band data in-line, the out-of-band (expedited) data is treated as normal data and the application should register an interest in, and will receive, FD_READ events, not FD_OOB events. An application can set or inspect the way in which out-of-band data is to be handled by using setsockopt or getsockopt for the SO_OOBINLINE option.

The error code in an FD_CLOSE message indicates whether the socket close was graceful or abortive. If the error code is zero, then the close was graceful; if the error code is WSAECONNRESET, then the socket's virtual socket was reset. This applies only to sockets of type SOCK_STREAM.

The FD_CLOSE message is posted when a close indication is received for the virtual circuit corresponding to the socket. In TCP terms, this means that the FD_CLOSE is posted when the connection goes into the FIN WAIT or CLOSE WAIT states. This results from the remote end performing a shutdown on the send side or a closesocket.

Please note your application will receive ONLY an FD_CLOSE message to indicate closure of a virtual circuit. It will NOT receive an FD_READ message to indicate this condition.

See Also

accept, closesocket, getsockopt, ioctlsocket, listen, PostMessage, recv, recvfrom, select, send, sendto, setsockopt, WSAStartup


WSACancelAsyncRequest

The Windows Sockets WSACancelAsyncRequest function cancels an incomplete asynchronous operation.

int WSACancelAsyncRequest(

HANDLE hAsyncTaskHandle
);
Parameters

hAsyncTaskHandle

Specifies the asynchronous operation to be canceled.

Return Value

The value returned by WSACancelAsyncRequest is zero if the operation was successfully canceled. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINVAL	Indicates that the specified asynchronous task handle was invalid
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
WSAEALREADY	The asynchronous routine being canceled has already completed.
Remarks

The WSACancelAsyncRequest function is used to cancel an asynchronous operation initiated by one of the WSAAsyncGetXByY family of functions such as WSAAsyncGetHostByName. The operation to be canceled is identified by the hAsyncTaskHandle parameter, which should be set to the asynchronous task handle as returned by the initiating function.

An attempt to cancel an existing asynchronous WSAAsyncGetXByY operation can fail with an error code of WSAEALREADY for two reasons. First, the original operation has already completed and the application has dealt with the resultant message. Second, the original operation has already completed but the resultant message is still waiting in the application window queue.

Notes for Windows Sockets Suppliers

It is unclear whether the application can usefully distinguish between WSAEINVAL and WSAEALREADY, since in both cases the error indicates that there is no asynchronous operation in progress with the indicated handle. [Trivial exception: zero is always an invalid asynchronous task handle.] The Windows Sockets specification does not prescribe how a conformant Windows Sockets implementation should distinguish between the two cases. For maximum portability, a Windows Sockets application should treat the two errors as equivalent.

See Also

WSAAsyncGetHostByAddr, WSAAsyncGetHostByName, WSAAsyncGetProtoByName, WSAAsyncGetProtoByNumber, WSAAsyncGetServByName, WSAAsyncGetServByPort, WSAStartup


WSACancelBlockingCall

The Windows Sockets WSACancelBlockingCall function cancels a blocking call that is currently in progress.

int WSACancelBlockingCall(void);

Return Value

The value returned by WSACancelBlockingCall is zero if the operation was successfully canceled. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINVAL	Indicates that there is no outstanding blocking call.
Remarks

This function cancels any outstanding blocking operation for this task. It is typically used in two situations:

1.	An application is processing a message that was received while a blocking call is in progress. In this case, WSAIsBlocking will be true.

2.	A blocking call is in progress, and Windows Sockets has called back to the application's "blocking hook" function (as established by WSASetBlockingHook).

In each case, the original blocking call will terminate as soon as possible with the error WSAEINTR. In (1), the termination will not take place until Windows message scheduling has caused control to revert to the blocking routine in Windows Sockets. In (2), the blocking call will be terminated as soon as the blocking hook function completes.

In the case of a blocking connect operation, the Windows Sockets implementation will terminate the blocking call as soon as possible, but it may not be possible for the socket resources to be released until the connection has completed (and then been reset) or timed out. This is likely to be noticeable only if the application immediately tries to open a new socket (if no sockets are available), or to connect to the same peer.

Canceling an accept or a select call does not adversely impact the sockets passed to these calls. Only the particular call fails; any operation that was legal before the cancel is legal after the cancel, and the state of the socket is not affected in any way.

Canceling any operation other than accept and select can leave the socket in an indeterminate state. If an application cancels a blocking operation on a socket, the only operation that the application can depend on being able to perform on the socket is a call to closesocket, although other operations may work on some Windows Sockets implementations. If an application needs maximum portability, it must not depend on performing operations after a cancel. An application can reset the connection by setting the timeout on SO_LINGER to zero.

If a cancel operation compromised the integrity of a SOCK_STREAM's data stream in any way, the Windows Sockets implementation must reset the connection and fail all future operations other than closesocket with WSAECONNABORTED.

Note that it is possible that the network operation completes before the WSACancelBlockingCall is processed, for example if data is received into the user buffer at interrupt time while the application is in a blocking hook. In this case, the blocking operation will return successfully as if WSACancelBlockingCall had never been called. The WSACancelBlockingCall still succeeds in this case; the only way to know with certainty that an operation was actually canceled is to check for a return code of WSAEINTR from the blocking call.

See Also

accept, closesocket, connect, select, WSAStartup


WSACleanup

The Windows Sockets WSACleanup function terminates use of the Windows Sockets DLL.

int WSACleanup(void);

Return Value

The return value is zero if the operation was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
Remarks

An application or DLL is required to perform a (successful) WSAStartup call before it can use Windows Sockets services. When it has completed the use of Windows Sockets, the application or DLL must call WSACleanup to deregister itself from a Windows Sockets implementation and allow the implementation to free any resources allocated on behalf of the application or DLL. Any open SOCK_STREAM sockets that are connected when WSACleanup is called are reset; sockets that have been closed with closesocket but still have pending data to be sent are not affected — the pending data is still sent.

There must be a call to WSACleanup for every call to WSAStartup made by a task. Only the final WSACleanup for that task does the actual cleanup; the preceding calls simply decrement an internal reference count in the Windows Sockets DLL. A naive application can ensure that WSACleanup was called enough times by calling WSACleanup in a loop until it returns WSANOTINITIALISED.

Attempting to call WSACleanup from within a blocking hook and then failing to check the return code is a common error in Windows Sockets programming. If an application needs to quit while a blocking call is outstanding, the application must first cancel the blocking call with WSACancelBlockingCall then issue the WSACleanup call once control has been returned to the application.

Notes for Windows Sockets Suppliers

Well-behaved Windows Sockets applications will make a WSACleanup call to indicate deregistration from a Windows Sockets implementation. This function can thus, for example, be utilized to free up resources allocated to the specific application.

A Windows Sockets implementation must be prepared to deal with an application that terminates without invoking WSACleanup — for example, as a result of an error.

In a multithreaded environment, WSACleanup terminates Windows Sockets operations for all threads.

A Windows Sockets implementation must ensure that WSACleanup leaves things in a state in which the application can invoke WSAStartup to reestablish Windows Sockets usage.

See Also

WSACancelBlockingCall, WSAStartup,


WSAGetLastError

The Windows Sockets WSAGetLastError function gets the error status for the last operation that failed.

int WSAGetLastError(void);

Return Value

The return value indicates the error code for the last Windows Sockets function performed by this thread.

Notes for Windows Sockets Suppliers

The use of the WSAGetLastError function to retrieve the last error code, rather than relying on a global error variable (compare errno), is required in order to provide compatibility with future multithreaded environments.

Note that in a nonpreemptive Windows environment WSAGetLastError is used to retrieve only Windows Sockets function errors. In a preemptive environment, WSAGetLastError will invoke GetLastError, which is used to retrieve the error status for all Win32 functions on a per-thread basis. For portability, an application should use WSAGetLastError immediately after the Windows Sockets function that failed. For more information, see Error Codes.

Remarks

This function returns the last network error that occurred. When a particular Windows Sockets function indicates that an error has occurred, this function should be called to retrieve the appropriate error code.

See Also

GetLastError, WSASetLastError


WSAIsBlocking

The Windows Sockets WSAIsBlocking function determines if a blocking call is in progress.

BOOL WSAIsBlocking(void);

Return Value

The return value is TRUE if there is an outstanding blocking function awaiting completion. Otherwise, it is FALSE.

Remarks

This function allows a task to determine if it is executing while waiting for a previous blocking call to complete.

Although a call issued on a blocking socket appears to an application program as though it "blocks," the Windows Sockets DLL has to relinquish the processor to allow other applications to run. This means that it is possible for the application that issued the blocking call to be reentered, depending on the message(s) it receives. In this instance, the WSAIsBlocking function can be used to ascertain whether the task has been reentered while waiting for an outstanding blocking call to complete. Note that Windows Sockets prohibits more than one outstanding call per thread.

Notes for Windows Sockets Suppliers

A Windows Sockets implementation must prohibit more than one outstanding blocking call per thread.


WSASetBlockingHook

The Windows Sockets WSASetBlockingHook function establishes an application-specific blocking hook function.

FARPROC WSASetBlockingHook(

FARPROC lpBlockFunc
);
Parameters

lpBlockFunc

A pointer to the procedure instance address of the blocking function to be installed.

Return Value

The return value is a pointer to the procedure-instance of the previously installed blocking function. The application or library that calls the WSASetBlockingHook  function should save this return value so that it can be restored if necessary. (If "nesting" is not important, the application can simply discard the value returned by WSASetBlockingHook and eventually use WSAUnhookBlockingHook to restore the default mechanism.) If the operation fails, a NULL pointer is returned, and a specific error number can be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEINPROGRESS	A blocking Windows Sockets operation is in progress.
Remarks

This function installs a new function which a Windows Sockets implementation should use to implement blocking socket function calls.

A Windows Sockets implementation includes a default mechanism by which blocking socket functions are implemented. The function WSASetBlockingHook gives the application the ability to execute its own function at blocking time in place of the default function.

When an application invokes a blocking Windows Sockets operation, the Windows Sockets implementation initiates the operation and then enters a loop similar to the following pseudocode:

for(;;) {

    /* flush messages for good user response */

    while (BlockingHook)

        ;

    /* check for WSACancelBlockingCall */

    if(operation_cancelled)

       break;

    /* check to see if operation completed */

    if(operation_complete)

        break;        /* normal completion */

}

Note that Windows Sockets implementations can perform the above steps in a different order; for example, the check for operation completion may occur before calling the blocking hook. The default BlockingHook function is equivalent to:

BOOL DefaultBlockingHook(void)

{

    MSG msg;

    BOOL ret;

    /* get the next message, if any */

    ret = (BOOL) PeekMessage(&msg, NULL, 0, 0, PM_REMOVE);

    /* if we got one, process it */

    if (ret) {

        TranslateMessage(&msg);

        DispatchMessage(&msg);

    }

    /* TRUE if we got a message */

    return ret;

}

The WSASetBlockingHook function is provided to support those applications that require more complex message processing — for example, those employing the MDI (multiple document interface) model. It is not intended as a mechanism for performing general applications functions. In particular, the only Windows Sockets function that can be issued from a custom blocking hook function is WSACancelBlockingCall, which will cause the blocking loop to terminate.

This function must be implemented on a per-task basis for non-multithreaded versions of Windows and on a per-thread basis for multithreaded versions of Windows such as Windows NT. It thus provides for a particular task or thread to replace the blocking mechanism without affecting other tasks or threads.

In multithreaded versions of Windows, there is no default blocking hook — blocking calls block the thread that makes the call. However, an application can install a specific blocking hook by calling WSASetBlockingHook.

This allows easy portability of applications that depend on the blocking hook behavior.

See Also

WSACancelBlockingCall, WSAUnhookBlockingHook


WSASetLastError

The Windows Sockets WSASetLastError function sets the error code that can be retrieved by WSAGetLastError.

void WSASetLastError(

int iError
);
Parameters

iError

Specifies the error code to be returned by a subsequent WSAGetLastError call.

Return Value

This function does not return a value.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
Remarks

This function allows an application to set the error code to be returned by a subsequent WSAGetLastError call for the current thread. Note that any subsequent Windows Sockets function called by the application will override the error code as set by this function.

Notes for Windows Sockets Suppliers

In a Win32 environment, this function will invoke SetLastError.

See Also

SetLastError, WSAGetLastError


WSAStartup

int WSAStartup(

WORD wVersionRequested,
LPWSADATA lpWSAData
);
Parameters

wVersionRequested

The highest version of Windows Sockets support that the caller can use. The high-order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.

lpWSAData

A pointer to the WSADATA data structure that is to receive details of the Windows Sockets implementation.

Return Value

WSAStartup returns zero if successful. Otherwise, it returns one of the error codes listed below. Note that the normal mechanism whereby the application calls WSAGetLastError to determine the error code cannot be used, since the Windows Sockets DLL may not have established the client data area where the "last error" information is stored.

Notes for Windows Sockets Suppliers

Each Windows Sockets application MUST make a WSAStartup call before issuing any other Windows Sockets API calls. This function can thus be used for initialization purposes.

Further issues are discussed in the notes for WSACleanup.

Error Codes

WSASYSNOTREADY	Indicates that the underlying network subsystem is not ready for network communication.
WSAVERNOTSUPPORTED	The version of Windows Sockets support requested is not provided by this particular Windows Sockets implementation.
WSAEINVAL	The Windows Sockets version specified by the application is not supported by this DLL.
Remarks

This function must be the first Windows Sockets function called by an application or DLL. It allows an application or DLL to specify the version of Windows Sockets required and to retrieve details of the specific Windows Sockets implementation. The application or DLL may only issue further Windows Sockets functions after a successful WSAStartup invocation.

In order to support future Windows Sockets implementations and applications that may have functionality differences from Windows Sockets 1.1, a negotiation takes place in WSAStartup. The caller of WSAStartup and the Windows Sockets DLL indicate to each other the highest version that they can support, and each confirms that the other's highest version is acceptable. Upon entry to WSAStartup, the Windows Sockets DLL examines the version requested by the application. If this version is higher than the lowest version supported by the DLL, the call succeeds and the DLL returns in wHighVersion the highest version it supports and in wVersion the minimum of its high version and wVersionRequested. The Windows Sockets DLL then assumes that the application will use wVersion. If the wVersion field of the WSADATA structure is unacceptable to the caller, it should call WSACleanup and either search for another Windows Sockets DLL or fail to initialize.

This negotiation allows both a Windows Sockets DLL and a Windows Sockets application to support a range of Windows Sockets versions. An application can successfully use a Windows Sockets DLL if there is any overlap in the version ranges. The following chart gives examples of how WSAStartup works in conjunction with different application and Windows Sockets DLL versions:

App versions	DLL Versions	wVersionRequested	wVersion	wHighVersion	End Result
1.1	1.1	1.1	1.1	1.1	use 1.1
1.0 1.1	1.0	1.1	1.0	1.0	use 1.0
1.0	1.0 1.1	1.0	1.0	1.1	use 1.0
1.1	1.0 1.1	1.1	1.1	1.1	use 1.1
1.1	1.0	1.1	1.0	1.0	Application fails
1.0	1.1	1.0	---	---	WSAVERNOTSUPPORTED
1.0 1.1	1.0 1.1	1.1	1.1	1.1	use 1.1
1.1 2.0	1.1	2.0	1.1	1.1	use 1.1
2.0	1.1	2.0	1.1	1.1	Application fails
The following code fragment demonstrates how an application that supports only version 1.1 of Windows Sockets makes a WSAStartup call:

WORD wVersionRequested;

WSADATA wsaData;

int err;

wVersionRequested = MAKEWORD(1, 1);

err = WSAStartup(wVersionRequested, &wsaData);

if (err != 0)

    /* Tell the user that we couldn't find a useable */

    /* winsock.dll.     */

    return;

/* Confirm that the Windows Sockets DLL supports 1.1.*/

/* Note that if the DLL supports versions greater */

/* than 1.1 in addition to 1.1, it will still return */

/* 1.1 in wVersion since that is the version we */

/* requested. */

if ( LOBYTE( wsaData.wVersion ) != 1 ||

        HIBYTE( wsaData.wVersion ) != 1 ) {

    /* Tell the user that we couldn't find a useable */

    /* winsock.dll. */

    WSACleanup();

    return;

}

/* The Windows Sockets DLL is acceptable. Proceed. */

This code fragment demonstrates how a Windows Sockets DLL that supports only version 1.1 performs the WSAStartup negotiation:

/* Make sure that the version requested is >= 1.1. */

/* The low byte is the major version and the high */

/* byte is the minor version.   */

if ( LOBYTE( wVersionRequested ) < 1 ||

        ( LOBYTE( wVersionRequested ) == 1 &&

        HIBYTE( wVersionRequested ) < 1 )

    return WSAVERNOTSUPPORTED;

/* Since we only support 1.1, set both wVersion and */

/* wHighVersion to 1.1. */

lpWsaData->wVersion = MAKEWORD( 1, 1 );

lpWsaData->wHighVersion = MAKEWORD( 1, 1 );

Once an application or DLL has made a successful WSAStartup call, it may proceed to make other Windows Sockets calls as needed. When it has finished using the services of the Windows Sockets DLL, the application or DLL must call WSACleanup in order to allow the Windows Sockets DLL to free any resources for the application.

Details of the actual Windows Sockets implementation are described in the WSAData structure defined as follows:

struct WSAData {

    WORD            wVersion;

    WORD            wHighVersion;

    char            szDescription[WSADESCRIPTION_LEN+1];

    char            szSystemStatus[WSASYSSTATUS_LEN+1];

    unsigned short  iMaxSockets;

    unsigned short  iMaxUdpDg;

    char FAR *      lpVendorInfo;

};

The members of this structure are:

Members	Usage
wVersion	The version of the Windows Sockets specification that the Windows Sockets DLL expects the caller to use.
wHighVersion	The highest version of the Windows Sockets specification that this DLL can support (also encoded as shown previously). Typically, this will be the same as wVersion.
szDescription	A null-terminated ASCII string into which the Windows Sockets DLL copies a description of the Windows Sockets implementation, including vendor identification. The text (up to 256 characters in length) may contain any characters, but vendors are cautioned against including control and formatting characters: the most likely use that an application will put this to is to display it (possibly truncated) in a status message.
szSystemStatus	A null-terminated ASCII string into which the Windows Sockets DLL copies relevant status or configuration information. The Windows Sockets DLL should use this field only if the information might be useful to the user or support staff: it should not be considered an extension of the szDescription field.
iMaxSockets	The maximum number of sockets that a single process can open. A Windows Sockets implementation can provide a global pool of sockets for allocation to any process; alternatively, it can allocate per-process resources for sockets. The number may well reflect the way the Windows Sockets DLL or the networking software was configured. Application writers may use this number as a crude indication of whether the Windows Sockets implementation is usable by the application. For example, an X Windows server might check iMaxSockets when first started: if it is less than 8, the application would display an error message instructing the user to reconfigure the networking software. (This is a situation in which the szSystemStatus text might be used.) Obviously, there is no guarantee that a particular application can actually allocate iMaxSockets sockets, since there may be other Windows Sockets applications in use.
iMaxUdpDg	The size, in bytes, of the largest UDP datagram that can be sent or received by a Windows Sockets application. If the implementation imposes no limit, iMaxUdpDg is zero. In many implementations of Berkeley sockets, there is an implicit limit of 8192 bytes on UDP datagrams (which are fragmented if necessary). A Windows Sockets implementation can impose a limit based, for instance, on the allocation of fragment reassembly buffers. The minimum value of iMaxUdpDg for a Windows Sockets-compliant implementation is 512. Note that regardless of the value of iMaxUdpDg, it is inadvisable to attempt to send a broadcast datagram larger than the Maximum Transmission Unit (MTU) for the network. (Windows Sockets does not provide a mechanism to discover the MTU, but it must be no less than 512 bytes.)
lpVendorInfo	A far pointer to a vendor-specific data structure. The definition of this structure (if supplied) is beyond the scope of this documentation.
An application or DLL can call WSAStartup more than once if it needs to obtain the WSAData structure information more than once. However, the wVersionRequired parameter is assumed to be the same on all calls to WSAStartup; that is, an application or DLL cannot change the version of Windows Sockets it expects after the initial call to WSAStartup.

There must be one WSACleanup call corresponding to every WSAStartup call to allow third-party DLLs to make use of a Windows Sockets DLL on behalf of an application. This means, for example, that if an application calls WSAStartup three times, it must call WSACleanup three times. The first two calls to WSACleanup do nothing except decrement an internal counter; the final WSACleanup call for the task deallocates all necessary resources for the task.

See Also

send, sendto, WSACleanup


WSAUnhookBlockingHook

The Windows Sockets WSAUnhookBlockingHook function restores the default blocking hook function.

int WSAUnhookBlockingHook(

void
);
Remarks

This function removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism.

WSAUnhookBlockingHook will always install the default mechanism, not the previous mechanism. If an application needs to nest blocking hooks — that is, to establish a temporary blocking hook function and then revert to the previous mechanism (whether the default or one established by an earlier WSASetBlockingHook) — it must save and restore the value returned by WSASetBlockingHook; it cannot use WSAUnhookBlockingHook.

In multithreaded versions of Windows such as Windows NT, there is no default blocking hook. Calling WSAUnhookBlockingHook disables any blocking hook installed by the application and any blocking calls made block the thread that made the call.

Return Value

The return value is zero if the operation was successful. Otherwise, the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
See Also

WSASetBlockingHook


wsprintf

The wsprintf function formats and stores a series of characters and values in a buffer. Any arguments are converted and copied to the output buffer according to the corresponding format specification in the format string. The function appends a terminating null character to the characters it writes, but the return value does not include the terminating null character in its character count.

int wsprintf(

LPTSTR  lpOut,	// address of buffer for output
LPCTSTR  lpFmt	// address of format-control string
...	// optional arguments
);
Parameters

lpOut

Points to a buffer to receive the formatted output.

lpFmt

Points to a null-terminated string that contains the format-control specifications. In addition to ordinary ASCII characters, a format specification for each argument appears in this string. For more information about the format specification, see the Remarks section.

...

Specifies one or more optional arguments. The number and type of argument parameters depend on the corresponding format-control specifications in the lpFmt parameter.

Return Value

If the function succeeds, the return value is the number of characters stored in the output buffer, not counting the terminating null character.

If the function fails, the return value is less than the length of the format-control string. To get extended error information, call GetLastError.

Remarks

The format-control string contains format specifications that determine the output format for the arguments following the lpFmt parameter. Format specifications, discussed below, always begin with a percent sign (%). If a percent sign is followed by a character that has no meaning as a format field, the character is not formatted (for example, %% produces a single percent-sign character).

The format-control string is read from left to right. When the first format specification (if any) is encountered, it causes the value of the first argument after the format-control string to be converted and copied to the output buffer according to the format specification. The second format specification causes the second argument to be converted and copied, and so on. If there are more arguments than format specifications, the extra arguments are ignored. If there are not enough arguments for all of the format specifications, the results are undefined.

A format specification has the following form:

%[-][#][0][width][.precision]type

Each field is a single character or a number signifying a particular format option. The type characters that appear after the last optional format field determine whether the associated argument is interpreted as a character, a string, or a number. The simplest format specification contains only the percent sign and a type character (for example, %s). The optional fields control other aspects of the formatting. Following are the optional and required fields and their meanings:

Field	Meaning
−	Pad the output with blanks or zeros to the right to fill the field width, justifying output to the left. If this field is omitted, the output is padded to the left, justifying it to the right.
#	Prefix hexadecimal values with 0x (lowercase) or 0X (uppercase).
0	Pad the output value with zeros to fill the field width. If this field is omitted, the output value is padded with blank spaces.
width	Copy the specified minimum number of characters to the output buffer. The width field is a nonnegative integer. The width specification never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or if the width field is not present, all characters of the value are printed, subject to the precision specification.
.precision	For numbers, copy the specified minimum number of digits to the output buffer. If the number of digits in the argument is less than the specified precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds the specified precision. If the specified precision is 0 or omitted entirely, or if the period (.) appears without a number following it, the precision is set to 1.
	For strings, copy the specified maximum number of characters to the output buffer.
type	Output the corresponding argument as a character, a string, or a number. This field can be any of the following character sequences:
Sequence	Insert
c	A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is interpreted as type WCHAR when the calling application uses the #define UNICODE compile flag and as type CHAR otherwise.
C	A single character. This sequence is interpreted as type CHAR when the calling application uses the #define UNICODE compile flag and as type WCHAR otherwise.
d	A signed decimal integer argument. This sequence is equivalent to the i sequence.
hc, hC	A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is always interpreted as type CHAR, even when the calling application uses the #define UNICODE compile flag.
hs, hS	A string. This sequence is always interpreted as type LPSTR, even when the calling application uses the #define UNICODE compile flag.
i	A signed decimal integer. This sequence is equivalent to the d sequence.
lc, lC	A single character. The wsprintf function ignores character arguments with a numeric value of zero. This sequence is always interpreted as type WCHAR, even when the calling application does not use the #define UNICODE compile flag.
ld	A long signed decimal integer. This sequence is equivalent to the li sequence.
li	A long signed decimal integer. This sequence is equivalent to the ld sequence.
ls, lS	A string. This sequence is always interpreted as type LPWSTR, even when the calling application does not use the #define UNICODE compile flag. This sequence is equivalent to the ws sequence.
lu	A long unsigned integer.
lx, lX	A long unsigned hexadecimal integer in lowercase or uppercase.
s	A string. This sequence is interpreted as type LPWSTR when the calling application uses the #define UNICODE compile flag and as type LPSTR otherwise.
S	A string. This sequence is interpreted as type LPSTR when the calling application uses the #define UNICODE compile flag and as type LPWSTR otherwise.
u	An unsigned integer argument.
x, X	An unsigned hexadecimal integer in lowercase or uppercase.
Note  Unlike other Windows functions, wsprintf uses the C calling convention (_cdecl), rather than the Pascal calling convention. As a result, it is the responsibility of the calling process to pop arguments off the stack, and arguments are pushed on the stack from right to left. In C-language modules, the C compiler performs this task.

See Also

wvsprintf


wvsprintf

The wvsprintf function formats and stores a series of characters and values in a buffer. The items pointed to by the argument list are converted and copied to an output buffer according to the corresponding format specification in the format-control string. The function appends a terminating null character to the characters it writes, but the return value does not include the terminating null character in its character count.

int wvsprintf(

LPTSTR  lpOutput,	// address of buffer for output
LPCTSTR  lpFormat,	// address of format-control string
va_list  arglist	// variable argument list of format-control arguments
);
Parameters

lpOutput

Points to a buffer to receive the formatted output.

lpFormat

Points to a null-terminated string that contains the format-control specifications. In addition to ordinary ASCII characters, a format specification for each argument appears in this string. For more information about the format specification, see the wsprintf function.

arglist

A variable argument list; each element of the list specifies an argument for the format-control string. The number, type, and interpretation of the arguments depend on the corresponding format-control specifications in the lpFmt parameter.

Return Value

If the function succeeds, the return value is the number of characters stored in the buffer, not counting the terminating null character.

If the function fails, the return value is less than the length of the format-control string. To get extended error information, call GetLastError.

Remarks

The function copies the format-control string into the output buffer character by character, starting with the first character in the string. When it encounters a format specification in the string, the function retrieves the value of the next available argument (starting with the first argument in the list), converts that value into the specified format, and copies the result to the output buffer. The function continues to copy characters and expand format specifications in this way until it reaches the end of the format-control string. If there are more arguments than format specifications, the extra arguments are ignored. If there are not enough arguments for all of the format specifications, the results are undefined.

See Also

wsprintf


Yield

The Yield function is obsolete. In the Win32-based application programming interface (API), this function does nothing.

Threads that contain windows should use the DispatchMessage, PeekMessage, or TranslateMessage functions. The message-loop functions handle message synchronization properly and yield at the appropriate times.

Threads that do not contain windows should use the Sleep function with a sleep time of zero milliseconds to give up the remainder of their current time slice.

See Also

DispatchMessage, PeekMessage, Sleep, TranslateMessage


ZeroMemory

The ZeroMemory function fills a block of memory with zeros.

VOID ZeroMemory(

PVOID  Destination	// address of block to fill with zeros
DWORD  Length	// size, in bytes, of block to fill with zeros
);
Parameters

Destination

Points to the starting address of the block of memory to fill with zeros.

Length

Specifies the size, in bytes, of the block of memory to fill with zeros.

Return Value

This function has no return value.

See Also

CopyMemory, FillMemory, MoveMemory


LZOpenFile

The LZOpenFile function creates, opens, reopens, or deletes the specified file.

INT LZOpenFile(

LPTSTR  lpFileName,	// address of name of file to be opened
LPOFSTRUCT  lpReOpenBuf,	// address of open file structure
WORD  wStyle	// action to take
);
Parameters

lpFileName

Points to a string that specifies the name of a file.

lpReOpenBuf

Points to the OFSTRUCT structure that is to receive information about the file when the file is first opened. The structure can be used in subsequent calls to the LZOpenFile function to refer to the open file.

The szPathName member of this structure contains characters from the original equipment manufacturer (OEM) character set.

wStyle

Specifies the action to take. This parameter can be a combination of the following values:

Value	Meaning
OF_CANCEL	Ignored. In the Win32-based application programming interface (API), the OF_PROMPT style produces a dialog box containing a Cancel button.
OF_CREATE	Directs LZOpenFile to create a new file. If the file already exists, it is truncated to zero length.
OF_DELETE	Deletes the file.
OF_EXIST	Opens the file and then closes it to test for a file's existence.
OF_PARSE	Fills the OFSTRUCT structure but carries out no other action.
OF_PROMPT	Displays a dialog box if the requested file does not exist. The dialog box informs the user that Windows cannot find the file, and it contains Retry and Cancel buttons. Choosing the Cancel button directs LZOpenFile to return a "file not found" error message.
OF_READ	Opens the file for reading only.
OF_READWRITE	Opens the file for reading and writing.
OF_REOPEN	Opens the file using information in the reopen buffer.
OF_SHARE_DENY_NONE	Opens the file without denying other processes read or write access to the file. LZOpenFile fails if the file has been opened in compatibility mode by any other process.
OF_SHARE_DENY_READ	Opens the file and denies other processes read access to the file. LZOpenFile fails if the file has been opened in compatibility mode or has been opened for read access by any other process.
OF_SHARE_DENY_WRITE	Opens the file and denies other processes write access to the file. LZOpenFile fails if the file has been opened in compatibility mode or has been opened for write access by any other process.
OF_SHARE_EXCLUSIVE	Opens the file in exclusive mode, denying other processes both read and write access to the file. LZOpenFile fails if the file has been opened in any other mode for read or write access, even by the current process.
OF_WRITE	Opens the file for writing only.
Return Value

If the function succeeds and the value specified by the wStyle parameter is not OF_READ, the return value is a handle identifying the file. If the file is compressed and opened with wStyle set to OF_READ, the return value is a special file handle.

If the function fails, the return value is an LZERROR_* code. These codes have values less than zero. Note that LZOpenFile calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread's last-error code.

Here is a list of the LZERROR_* codes that LZOpenFile can return upon failure:

Value	Meaning
LZERROR_BADINHANDLE	The handle identifying the source file is not valid. The file cannot be read.
LZERROR_GLOBALLOC	The maximum number of open compressed files has been exceeded or local memory cannot be allocated.
Remarks

If the wStyle parameter is the OF_READ flag (or OF_READ and any of the OF_SHARE_ flags) and the file is compressed, LZOpenFile calls the LZInit function, which performs the required initialization for the decompression operations.

The handle this function returns is compatible only with the functions in LZEXPAND.DLL; it should not be used for other file operations.

See Also

LZClose, LZInit, LZRead


LZRead

The LZRead function reads (at most) the specified number of bytes from a file and copies them into a buffer.

INT LZRead(

INT  hFile,	// LZ file handle of file
LPSTR  lpBuffer,	// address of buffer for bytes
INT  cbRead	// count of bytes
);
Parameters

hFile

Identifies the source file.

lpBuffer

Points to a buffer that receives the bytes read from the file.

cbRead

Specifies the count of bytes to be read.

Return Value

If the function succeeds, the return value specifies the number of bytes read.

If the function fails, the return value is an LZERROR_* code. These codes have values less than zero. Note that LZRead calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread's last-error code.

Here is a list of the LZERROR_* codes that LZRead can return upon failure:

Value	Meaning
LZERROR_BADINHANDLE	The handle identifying the source file is not valid. The file cannot be read.
LZERROR_BADOUTHANDLE	The handle identifying the destination file is not valid. The file cannot be written.
LZERROR_BADVALUE	One of the input parameters is not valid.
LZERROR_GLOBALLOC	The maximum number of open compressed files has been exceeded or local memory cannot be allocated.
LZERROR_GLOBLOCK	The LZ file handle cannot be locked down.
LZERROR_READ	The source file format is not valid.
LZERROR_WRITE	There is insufficient space for the output file.
Remarks

The handle identifying the file must be retrieved by calling either the LZInit or LZOpenFile function.

If the file is compressed, LZRead emulates the _lread function on an expanded image of the file and copies the bytes of data into the specified buffer.

Applications must call the LZOpenFile, LZSeek, and LZRead functions instead of the OpenFile, _llseek, and _lread functions.

See Also

LZInit, LZOpenFile, LZSeek


LZSeek

The LZSeek function moves a file pointer a number of bytes from a starting position.

LONG LZSeek(

INT  hFile,	// handle of source file
LONG  lOffset,	// number of bytes to move
INT  iOrigin	// starting position
);
Parameters

hFile

Identifies the source file.

lOffset

Specifies the number of bytes by which to move the file pointer.

iOrigin

Specifies the starting position of the pointer. This parameter must be one of the following values:

Value	Meaning
0	Moves the file pointer lOffset bytes from the beginning of the file.
1	Moves the file pointer lOffset bytes from the current position.
2	Moves the file pointer lOffset bytes from the end of the file.
Return Value

If the function succeeds, the return value specifies the offset from the beginning of the file to the new pointer position.

If the function fails, the return value is an LZERROR_* code. These codes have values less than zero. Note that LZSeek calls neither SetLastError nor SetLastErrorEx; thus, its failure does not affect a thread's last-error code.

Upon failure, LZSeek can return the following LZERROR_* codes:

Value	Meaning
LZERROR_BADINHANDLE	The handle identifying the source file is not valid. The file cannot be read.
LZERROR_BADVALUE	One of the parameters is outside the range of acceptable values.
LZERROR_GLOBLOCK	The LZ file handle cannot be locked down.
Remarks

The handle identified by the hFile parameter must be retrieved by calling either the LZInit or LZOpenFile function.

If the file is compressed, LZSeek emulates the _llseek function on an expanded image of the file.

See Also

LZInit, LZOpenFile


LZStart

The LZStart function is obsolete. It is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should use the LZCopy function.


MakeAbsoluteSD

The MakeAbsoluteSD function creates a security descriptor in absolute format by using a security descriptor in self-relative format as a template.

BOOL MakeAbsoluteSD(

PSECURITY_DESCRIPTOR  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
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

A security descriptor in absolute format contains pointers to the information it contains, rather than the information itself. A security descriptor in self-relative format contains the information in a contiguous block of memory. In a self-relative security descriptor, a SECURITY_DESCRIPTOR structure always starts the information, but the security descriptor's other components can follow the structure in any order. Instead of using memory addresses, the components of the self-relative security descriptor are identified by offsets from the beginning of the security descriptor. This format is useful when an security descriptor must be stored on a floppy disk or transmitted by means of a communications protocol.

A server that copies secured objects to various media can use the MakeAbsoluteSD function to create an absolute security descriptor from a self-relative security descriptor and the MakeSelfRelativeSD function to create a self-relative security descriptor from an absolute security descriptor.

See Also

MakeSelfRelativeSD, SECURITY_DESCRIPTOR


MakeDragList  (preliminaryWindows NT)
MakeDragList  (preliminary−Windows NT)

The MakeDragList function changes the specified single-selection list box to a drag list box.

BOOL MakeDragList(

HWND  hLB
);
Parameters

hLB

Handle to the single-selection list box.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.


MakeProcInstance

The MakeProcInstance function is obsolete. Win32 functions can be called directly.

This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should not use this function.


MakeSelfRelativeSD

The MakeSelfRelativeSD function creates a security descriptor in self-relative format by using a security descriptor in absolute format as a template.

BOOL MakeSelfRelativeSD(

PSECURITY_DESCRIPTOR  psdAbsolute,	// address of absolute SD
PSECURITY_DESCRIPTOR  psdSelfRelative,	// address self-relative SD
LPDWORD  lpcbsdSelfRelative	// address of SD size
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

A security descriptor in absolute format contains pointers to the information it contains, rather than containing the information itself. A security descriptor in self-relative format contains the information in a contiguous block of memory. In a self-relative security descriptor, a SECURITY_DESCRIPTOR structure always starts the information, but the security descriptor's other components can follow the structure in any order. Instead of using memory addresses, the components of the security descriptor are identified by offsets from the beginning of the security descriptor. This format is useful when an security descriptor must be stored on a floppy disk or transmitted by means of a communications protocol.

A server that copies secured objects to various media can use the MakeSelfRelativeSD function to create a self-relative security descriptor from an absolute security descriptor and the MakeAbsoluteSD function to create an absolute security descriptor from a self-relative security descriptor.

See Also

MakeAbsoluteSD, SECURITY_DESCRIPTOR


MapDialogRect

The MapDialogRect function converts (maps) the specified dialog box units to screen units (pixels). The function replaces the coordinates in the specified RECT structure with the converted coordinates, which allows the structure to be used to create a dialog box or position a control within a dialog box.

BOOL MapDialogRect(

HWND  hwndDlg,	// handle of dialog box
LPRECT  lprc	// address of structure with rectangle
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The MapDialogRect function assumes that the initial coordinates in the RECT structure represent dialog box units. To convert these coordinates from dialog box units to pixels, the function retrieves the current horizontal and vertical base units for the dialog box, then applies the following formulas:

left   = (left   * baseunitX) / 4

right  = (right  * baseunitX) / 4

top    = (top    * baseunitY) / 8

bottom = (bottom * baseunitY) / 8

In most cases, the base units for the dialog box are the same as those retrieved by using the GetDialogBaseUnits function. If the dialog box template has the DS_SETFONT style, however, the base units are the average width and height, in pixels, of the characters in the font given by the template.

See Also

CreateDialog, CreateDialogIndirect, CreateDialogIndirectParam, CreateDialogParam, DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, GetDialogBaseUnits, RECT


MapGenericMask

The MapGenericMask function maps the generic access rights in an access mask to specific and standard access rights. The function applies a mapping supplied in a GENERIC_MAPPING structure.

VOID MapGenericMask(

PDWORD  pdwAccessMask,	// address of access mask
PGENERIC_MAPPING  pgm	// address of GENERIC_MAPPING structure
);
Parameters

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.

Return Value

This function does not return a value.

Remarks

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, GENERIC_MAPPING


MapViewOfFile

The MapViewOfFile function maps a view of a file into the address space of the calling process.

LPVOID MapViewOfFile(

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
);
Parameters

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-write access. The hMapObject parameter must have been created with PAGE_READWRITE protection. A read-write view of the file is mapped.
FILE_MAP_READ	Read-only access. The 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. If you create the map with PAGE_WRITECOPY and the view with FILE_MAP_COPY, you will receive a view to file. If you write to it, the pages are automatically swappable and the modifications you make will not go to the original data file. Windows 95: You must pass PAGE_WRITECOPY to CreateFileMapping; otherwise, an error will be returned. If you share the mapping between multiple processes using DupHandle or OpenFileMapping and one process writes to a view, the modification is propagated to the other process. The original file does not change. Windows NT: There is no restriction as to how the hMapObject parameter must be created. Copy on write is valid for any type of view.  If you share the mapping between multiple processes using DupHandle or OpenFileMapping and one process writes to a view, the modification is not propagated to the other process. The original file does not change.
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.

Return Value

If the function succeeds, the return value is the starting address of the mapped view.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Mapping a file makes the specified portion of the file visible in the address space of the calling process.

Multiple views of a file (or a file-mapping object and its mapped file) are said to be "coherent" if they contain identical data at a specified time. This occurs if the file views are derived from the same file-mapping object. A process can duplicate a file-mapping object handle into another process by using the DuplicateHandle function, or another process can open a file-mapping object by name by using the OpenFileMapping function.

A mapped view of a file is not guaranteed to be coherent with a file being accessed by the ReadFile or WriteFile function.

Windows 95 only: MapViewOfFile may require the swapfile to grow. If the swapfile cannot, MapViewOfFile fails.

See Also

CreateFileMapping, DuplicateHandle, GetSystemInfo, MapViewOfFileEx, OpenFileMapping, UnmapViewOfFile, SYSTEM_INFO


MapViewOfFileEx

The MapViewOfFileEx function maps a view of a file into the address space of the calling process. This extended function allows the calling process to specify a suggested memory address for the mapped view.

This function is available for Win32-based applications only.

LPVOID MapViewOfFileEx(

HANDLE  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
);
Parameters

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-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. If you create the map with PAGE_WRITECOPY and the view with FILE_MAP_COPY, you will reeive a view to file. If you write to it, the pages are automatically swappable and the modifications you make will not go to the original data file. Windows 95: You must pass PAGE_WRITECOPY to CreateFileMapping; otherwise, an error will be returned. If you share the mapping between multiple processes using DupHandle or OpenFileMapping and one process writes to a view, the modification is propagated to the other process. The original file does not change. Windows NT: There is no restriction as to how the hMapObject parameter must be created. Copy on write is valid for any type of view.  If you share the mapping between multiple processes using DupHandle or OpenFileMapping and one process writes to a view, the modification is not propagated to the other process. The original file does not change.
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.

Return Value

If the function succeeds, the return value is the starting address of the mapped view.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

Mapping a file makes the specified portion of the file visible in the address space of the calling process.

If a suggested mapping address is supplied, the file is mapped at the specified address (rounded down to the nearest 64K boundary) if there is enough address space at the specified address. If there is not, the function fails.

Typically, the suggested address is used to specify that a file should be mapped at the same address in multiple processes. This requires the region of address space to be available in all involved processes. No other memory allocation, including use of the VirtualAlloc function to reserve memory, can take place in the region used for mapping.

Multiple views of a file (or a file-mapping object and its mapped file) are said to be "coherent" if they contain identical data at a specified time. This occurs if the file views are derived from the same file-mapping object. A process can duplicate a file-mapping object handle into another process by using the DuplicateHandle function, or another process can open a file-mapping object by name by using the OpenFileMapping function.

A mapped view of a file is not guaranteed to be coherent with a file being accessed by the ReadFile or WriteFile function.

See Also

CreateFileMapping, DuplicateHandle, GetSystemInfo, MapViewOfFile, OpenFileMapping, ReadFile, UnmapViewOfFile, SYSTEM_INFO, VirtualAlloc, WriteFile


MapVirtualKey

The MapVirtualKey function translates (maps) a virtual-key code into a scan code or character value, or translates a scan code into a virtual-key code.

UINT MapVirtualKey(

UINT  uCode,	// virtual-key code or scan code
UINT  fuMapType	// translation to perform
);
Parameters

uCode

Specifies the virtual-key code or scan code for a key. How this value is interpreted depends on the value of the 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.
Return Value

The return value is either a scan code, a virtual-key code, or a character value, depending on the value of uCode and fuMapType. If there is no translation, the return value is zero.

Remarks

An application can use MapVirtualKey to translate scan codes to the virtual-key code constants VK_SHIFT, VK_CONTROL, and VK_MENU, and vice versa. These translations do not distinguish between the left and right instances of the SHIFT, CTRL, or ALT keys. An application can get the scan code corresponding to the left or right instance of one of these keys by calling MapVirtualKey with uCode set to one of the following virtual-key code constants:

VK_LSHIFT	VK_RSHIFT
VK_LCONTROL	VK_RCONTROL
VK_LMENU	VK_RMENU
These left- and right-distinguishing constants are available to an application only through the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, and MapVirtualKey functions.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyState, SetKeyboardState


MapVirtualKeyEx  (preliminaryWindows 95)
MapVirtualKeyEx  (preliminary−Windows 95)

The MapVirtualKeyEx function translates (maps) a virtual-key code into a scan code or character value, or translates a scan code into a virtual-key code. The function translates the codes using the input language and physical keyboard layout identified by the given keyboard layout handle.

UINT MapVirtualKeyEx(

UINT  uCode,	// virtual-key code or scan code
UINT  fuMapType,	// translation to perform
HKL  hkl	// keyboard layout handle
);
Parameters

uCode

Specifies the virtual-key code or scan code for a key. How this value is interpreted depends on the value of the 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.
hkl

Identifies the keyboard layout to use for translating the given code. This parameter can be any keyboard layout handle previously returned by the LoadKeyboardLayout function.

Return Value

The return value is either a scan code, a virtual-key code, or a character value, depending on the value of uCode and fuMapType. If there is no translation, the return value is zero.

Remarks

An application can use MapVirtualKeyEx to translate scan codes to the virtual-key code constants VK_SHIFT, VK_CONTROL, and VK_MENU, and vice versa. These translations do not distinguish between the left and right instances of the SHIFT, CTRL, or ALT keys. An application can get the scan code corresponding to the left or right instance of one of these keys by calling MapVirtualKeyEx with uCode set to one of the following virtual-key code constants:

VK_LSHIFT	VK_RSHIFT
VK_LCONTROL	VK_RCONTROL
VK_LMENU	VK_RMENU
These left- and right-distinguishing constants are available to an application only through the GetKeyboardState, SetKeyboardState, GetAsyncKeyState, GetKeyState, MapVirtualKey, and MapVirtualKeyEx functions.

See Also

GetAsyncKeyState, GetKeyboardState, GetKeyState, LoadKeyboardLayout, MapVirtualKey, SetKeyboardState


MapWindowPoints

The MapWindowPoints function converts (maps) a set of points from a coordinate space relative to one window to a coordinate space relative to another window.

int MapWindowPoints(

HWND  hwndFrom,	// handle of window to be mapped from
HWND  hwndTo,	// handle of window to be mapped to
LPPOINT  lppt,	// address of structure array with points to map
UINT  cPoints	// number of structures in array
);
Parameters

hwndFrom

Identifies the window from which points are converted. If this parameter is NULL or HWND_DESKTOP, the points are presumed to be in screen coordinates.

hwndTo

Identifies the window to which points are converted. If this parameter is NULL or HWND_DESKTOP, the points are converted to screen coordinates.

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.

Return Value

If the function succeeds, the low-order word of the return value is the number of pixels added to the horizontal coordinate of each source point in order to compute the horizontal coordinate of each destination point; the high-order word is the number of pixels added to the vertical coordinate of each source point in order to compute the vertical coordinate of each destination point.

See Also

ClientToScreen, POINT, RECT, ScreenToClient


MaskBlt

The MaskBlt function combines the color data for the source and destination bitmaps using the specified mask and raster operation.

BOOL MaskBlt(

HDC  hdcDest,	// handle of destination device context
int  nXDest,	// x-coord. of upper-left corner of destination rectangle
int  nYDest,	// y-coord. of upper-left corner of destination rectangle
int  nWidth,	// width of source and destination rectangles
int  nHeight,	// height of source and destination rectangles
HDC  hdcSrc,	// handle of source device context
int  nXSrc,	// x-coord. of upper-left corner of source rectangle
int  nYSrc,	// y-coord. of upper-left corner of source rectangle
HBITMAP  hbmMask,	// handle of monochrome bit mask
int  xMask,	// horizontal pixel offset into the mask bitmap
int  yMask,	// vertical pixel offset into the mask bitmap
DWORD  dwRop	// raster operation code
);
Parameters

hdcDest

Identifies the destination device context.

nXDest

Specifies the logical x-coordinate of the upper-left corner of the destination rectangle.

nYDest

Specifies the logical y-coordinate of the upper-left corner of the destination rectangle.

nWidth

Specifies the width, in logical units, of the destination rectangle and source bitmap.

nHeight

Specifies the height, in logical units, of the destination rectangle and source bitmap.

hdcSrc

Identifies the device context from which the bitmap is to be copied. It must be zero if the dwRop parameter specifies a raster operation that does not include a source.

nXSrc

Specifies the logical x-coordinate of the upper-left corner of the source bitmap.

nYSrc

Specifies the logical y-coordinate of the upper-left corner of the source bitmap.

hbmMask

Identifies the monochrome mask bitmap combined with the color bitmap in the source device context.

xMask

Specifies the horizontal pixel offset for the mask bitmap specified by the hbmMask parameter.

yMask

Specifies the vertical pixel offset for the mask bitmap specified by the hbmMask parameter.

dwRop

Specifies both foreground and background ternary raster operation codes that the function uses to control the combination of source and destination data. The background raster operation code is stored in the high-order byte of the high-order word of this value; the foreground raster operation code is stored in the low-order byte of the high-order word of this value; the low-order word of this value is ignored, and should be zero. The macro MAKEROP4 creates such combinations of foreground and background raster operation codes.

For a discussion of foreground and background in the context of this function, see the following Remarks section.

For a list of common raster operation codes, see BitBlt .

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

A value of 1 in the mask specified by hbmMask indicates that the foreground raster operation code specified by dwRop should be applied at that location. A value of 0 in the mask indicates that the background raster operation code specified by dwRop should be applied at that location.

If the raster operations require a source, the mask rectangle must cover the source rectangle. If it does not, the function will fail. If the raster operations do not require a source, the mask rectangle must cover the destination rectangle. If it does not, the function will fail.

If a rotation or shear transformation is in effect for the source device context when this function is called, an error occurs. However, other types of transformation are allowed.

If the color formats of the source, pattern, and destination bitmaps differ, this function converts the pattern or source format, or both, to match the destination format.

If the mask bitmap is not a monochrome bitmap, an error occurs.

When an enhanced metafile is being recorded, an error occurs (and the function returns FALSE) if the source device context identifies an enhanced-metafile device context.

Not all devices support the MaskBlt function. An application should call the GetDeviceCaps function to determine whether a device supports this function.

If no mask bitmap is supplied, this function behaves exactly like BitBlt, using the foreground raster operation code.

The pixel offsets in the mask bitmap map to the point (0,0) in the source device context's bitmap. This is useful in cases where a mask bitmap contains a set of masks; an application can easily apply any one of them to a mask-block transfer task by adjusting the pixel offsets and rectangle sizes sent to MaskBlt.

See Also

BitBlt, GetDeviceCaps, PlgBlt, StretchBlt


MenuHelp  (preliminaryWindows NT)
MenuHelp  (preliminary−Windows NT)

The MenuHelp function processes WM_MENUSELECT and WM_COMMAND messages and displays help text about the current menu in the specified status window.

void MenuHelp(

UINT uMsg,
WPARAM wParam,
LPARAM lParam,
HMENU hMainMenu,
HINSTANCE hInst,
HWND hwndStatus,
UINT FAR *lpwIDs
);
Parameters

uMsg

WM_MENUSELECT or WM_COMMAND message.

wParam

First message parameter.

lParam

Second message parameter.

hMainMenu

Handle to the application's main menu.

hInst

Handle to the module that contains the string resources.

hwndStatus

Handle to the status window.

lpwIDs

Pointer to an array that contains pairs of string resource identifiers and menu handles. The function searches the array for the handle to the selected menu and, if found, uses the corresponding resource identifier to load the appropriate help string.

Return Value

This function does not return a value.

See Also

WM_COMMAND, WM_MENUSELECT


MenuItemFromPoint  (preliminaryWindows 95)
MenuItemFromPoint  (preliminary−Windows 95)

The MenuItemFromPoint function determines which menu item, if any, is at the specified location.

UINT WINAPI MenuItemFromPoint(

HWND  hWnd,
HMENU  hMenu,
POINT  ptScreen
);
Parameters

hWnd

Handle to the window containing the menu bar or pop-up menu.

hMenu

Handle to the menu containing the menu items to hit test.

ptScreen

POINT structure specifying the location to test. If hMenu specifies a menu bar, this parameter is in window coordinates. Otherwise, it is in client coordinates.

Return Value

Returns the zero-based position of the menu item at the specified location or −1 if no menu item is at the specified location.

See Also

POINT


MessageBeep

The MessageBeep function plays a waveform sound. The waveform sound for each sound type is identified by an entry in the [sounds] section of the registry.

BOOL MessageBeep(

UINT  fuType	// sound type
);
Parameters

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
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

After queuing the sound, the MessageBeep function returns control to the calling function and plays the sound asynchronously.

If it cannot play the specified alert sound, MessageBeep attempts to play the system default sound. If it cannot play the system default sound, the function produces a standard beep sound through the computer speaker.

The user can disable the warning beep by using the Control Panel Sound application.

See Also

FlashWindow, MessageBox


MessageBox

The MessageBox function creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons.

int MessageBox(

HWND  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
);
Parameters

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.  Depending on the hieracrchy of windows in the application, the user may be able to move to other windows within the application. all child windows of the parent of the message box are automatically disabled, but popup windows are not.  MB_APPLMODAL is the default value 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 button. Note that the first button is always the default unless MB_DEFBUTTON2 or MB_DEFBUTTON3 is specified.
MB_DEFBUTTON2	The second button is a default button.
MB_DEFBUTTON3	The third button is a default button.
MB_DEFBUTTON4	The fourth button is a default button.
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_SERVICE_NOTIFICATION	The caller is a service notifying the user of an event. The function brings up a message box on the current active desktop, even if there is no user logged on to the computer.
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.
Return Value

The return value is zero if there is not enough memory to create the message box.

If the function succeeds, the return value is one of the following menu-item values returned by the dialog box:

Value	Meaning
IDABORT	Abort button was selected.
IDCANCEL	Cancel button was selected.
IDIGNORE	Ignore button was selected.
IDNO	No button was selected.
IDOK	OK button was selected.
IDRETRY	Retry button was selected.
IDYES	Yes button was selected.
If a message box has a Cancel button, the function returns the IDCANCEL value if either the ESC key is pressed or the Cancel button is selected. If the message box has no Cancel button, pressing ESC has no effect.

Remarks

When you use a system-modal message box to indicate that the system is low on memory, the strings pointed to by the lpszText and lpszTitle parameters should not be taken from a resource file, because an attempt to load the resource may fail.

When an application calls MessageBox and specifies the MB_ICONHAND and MB_SYSTEMMODAL flags for the 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

The MessageBoxEx function creates, displays, and operates a message box. The message box contains an application-defined message and title, plus any combination of predefined icons and push buttons. The wLanguageId parameter specifies which set of language resources is used for the predefined push buttons. For full descriptions of the other parameters of MessageBoxEx, see  MessageBox .

int MessageBoxEx(

HWND  hwndOwner,	// handle of owner window
LPCTSTR  lpszText,	// address of text in message box
LPCTSTR  lpszCaption,	// address of title of message box
UINT  fuStyle,	// style of message box
WORD  wLanguageID	// language identifier
);
Parameters

hwndOwner

Identifies the owner window of the message box to be created. If this parameter is NULL, the message box has no owner window.

lpszCaption

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 button. Note that the first button is always the default unless MB_DEFBUTTON2 or MB_DEFBUTTON3 is specified.
MB_DEFBUTTON2	The second button is a default button.
MB_DEFBUTTON3	The third button is a default button.
MB_DEFBUTTON4	The fourth button is a default button.
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_SERVICE_NOTIFICATION	The caller is a service notifying the user of an event. The function brings up a message box on the current active desktop, even if there is no user logged on to the computer.
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 this release, the set of values is limited. For a list of the possible primary language identifiers and sublanguage identifiers, and a discussion of current language availability limitations, see the following Remarks section.

Return Value

If the function succeeds, the return value is a nonzero menu-item value returned by the dialog box.

Value	Meaning
IDABORT	Abort button was selected.
IDCANCEL	Cancel button was selected.
IDIGNORE	Ignore button was selected.
IDNO	No button was selected.
IDOK	OK button was selected.
IDRETRY	Retry button was selected.
IDYES	Yes button was selected.
If a message box has a Cancel button, the function returns the IDCANCEL value when either the ESC key or Cancel button is pressed. If the message box has no Cancel button, pressing the ESC key has no effect.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

When you create a system-modal message box to indicate that the system is low on memory, the strings passed as the 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 MessageBoxEx 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 each localized release usually contains only resources for that language. Thus, for example, the U.S. version offers LANG_ENGLISH, the French version offers LANG_FRENCH, the German version offers LANG_GERMAN, and the Japanese version offers LANG_JAPANESE. Each version offers LANG_NEUTRAL. This limits the set of values that can be used with the wLanguageID parameter. However, this may not apply in all cases. You should always enumerate the locales that are installed on a system befor using an LCID, whether in this function or any other that requires and LCID.

Primary Language Identifiers and Sublanguage Identifiers

Primary language: LANG_ NEUTRAL
Sublanguage: SUBLANG_ DEFAULT
Description: Default sublanguage

Primary language: LANG_ ALBANIAN
Sublanguage: None
Description: Albanian

Primary language: LANG_ ARABIC
Sublanguage: None
Description: Arabic

Primary language: LANG_ BAHASA
Sublanguage: None
Description: Bahasa (Indonesian)

Primary language: LANG_ BULGARIAN
Sublanguage: None
Description: Bulgarian

Primary language: LANG_ CATALAN
Sublanguage: None
Description: Catalan

Primary language: LANG_ CHINESE
Sublanguage: SUBLANG_ CHINESE_SIMPLIFIED
Description: Simplified Chinese

Primary language: LANG_ CHINESE
Sublanguage: SUBLANG_ CHINESE_TRADITIONAL
Description: Traditional Chinese

Primary language: LANG_ CZECH
Sublanguage: None
Description: Czech

Primary language: LANG_ DANISH
Sublanguage: None
Description: Danish

Primary language: LANG_ DUTCH
Sublanguage: SUBLANG_ DUTCH
Description: Dutch

Primary language: LANG_ DUTCH
Sublanguage: SUBLANG_ DUTCH_BELGIAN
Description: Belgian Dutch

Primary language: LANG_ ENGLISH
Sublanguage: SUBLANG_ ENGLISH_AUS
Description: Australian English

Primary language: LANG_ ENGLISH
Sublanguage: SUBLANG_ ENGLISH_UK
Description: UK English

Primary language: LANG_ ENGLISH
Sublanguage: SUBLANG_ ENGLISH_US
Description: US English

Primary language: LANG_ FINNISH
Sublanguage: None
Description: Finnish

Primary language: LANG_ FRENCH
Sublanguage: SUBLANG_ FRENCH
Description: French

Primary language: LANG_ FRENCH
Sublanguage: SUBLANG_ FRENCH_BELGIAN
Description: Belgian French

Primary language: LANG_ FRENCH
Sublanguage: SUBLANG_ FRENCH_CANADIAN
Description: Canadian French

Primary language: LANG_ FRENCH
Sublanguage: SUBLANG_ FRENCH_SWISS
Description: Swiss French

Primary language: LANG_ GERMAN
Sublanguage: SUBLANG_ GERMAN
Description: German

Primary language: LANG_ GERMAN
Sublanguage: SUBLANG_ GERMAN_SWISS
Description: Swiss German

Primary language: LANG_ GREEK
Sublanguage: None
Description: Greek

Primary language: LANG_ HEBREW
Sublanguage: None
Description: Hebrew

Primary language: LANG_ HUNGARIAN
Sublanguage: None
Description: Hungarian

Primary language: LANG_ ICELANDIC
Sublanguage: None
Description: Icelandic

Primary language: LANG_ ITALIAN
Sublanguage: SUBLANG_ ITALIAN
Description: Italian

Primary language: LANG_ ITALIAN
Sublanguage: SUBLANG_ ITALIAN_SWISS
Description: Swiss Italian

Primary language: LANG_ JAPANESE
Sublanguage: None
Description: Japanese

Primary language: LANG_ KOREAN
Sublanguage: None
Description: Korean

Primary language: LANG_ NORWEGIAN
Sublanguage: SUBLANG_ NORWEGIAN_BOKMAL
Description: Norwegian − Bokmal

Primary language: LANG_ NORWEGIAN
Sublanguage: SUBLANG_ NORWEGIAN_NYNORSK
Description: Norwegian − Nynorsk

Primary language: LANG_ POLISH
Sublanguage: None
Description: Polish

Primary language: LANG_ PORTUGUESE
Sublanguage: SUBLANG_ PORTUGUESE
Description: Portuguese

Primary language: LANG_ PORTUGUESE
Sublanguage: SUBLANG_ PORTUGUESE_BRAZILIAN
Description: Brazilian Portuguese

Primary language: LANG_ RHAETO_ROMAN
Sublanguage: None
Description: Rhaeto-Romanic

Primary language: LANG_ ROMANIAN
Sublanguage: None
Description: Romanian

Primary language: LANG_ RUSSIAN
Sublanguage: None
Description: Russian

Primary language: LANG_ SERBO_CROATIAN
Sublanguage: SUBLANG_ SERBO_CROATIAN_CYRILLIC
Description: Serbo-Croatian (Cyrillic)

Primary language: LANG_ SERBO_CROATIAN
Sublanguage: SUBLANG_ SERBO_CROATIAN_LATIN
Description: Croato-Serbian (Latin)

Primary language: LANG_ SLOVAK
Sublanguage: None
Description: Slovak

Primary language: LANG_ SPANISH
Sublanguage: SUBLANG_ SPANISH
Description: Spanish

Primary language: LANG_ SPANISH
Sublanguage: SUBLANG_ SPANISH_MEXICAN
Description: Spanish Mexican

Primary language: LANG_ SWEDISH
Sublanguage: None
Description: Swedish

Primary language: LANG_ THAI
Sublanguage: None
Description: Thai

Primary language: LANG_ TURKISH
Sublanguage: None
Description: Turkish

Primary language: LANG_ URDU
Sublanguage: None
Description: Urdu

See Also

MAKELANGID, MessageBeep, MessageBox, SetForegroundWindow


MessageBoxIndirect  (preliminaryWindows 95)
MessageBoxIndirect  (preliminary−Windows 95)

The MessageBoxIndirect function creates, displays, and operates a message box. The message box contains application-defined message text and title, any icon, and any combination of predefined push buttons.

BOOL API MessageBoxIndirect(

LPMSGBOXPARAMS lpMsgBoxParams	// address of structure for message box parameters
);
Parameters

lpMsgBoxParams

Points to a MSGBOXPARAMS structure that contains information used to display the message box.

See Also

MSGBOXPARAMS


MessageProc

The MessageProc hook procedure is an application-defined callback function the system calls after an input event occurs in a dialog box, message box, menu, or scroll bar, but before the message generated by the input event is processed. The hook procedure can monitor messages for a dialog box, message box, menu, or scroll bar created by a particular application or all applications.

LRESULT CALLBACK MessageProc(

int  nCode,	// hook code
WPARAM  wParam,	// undefined
LPARAM  lParam	// address of structure with message data
);
Parameters

nCode

Specifies the type of input event that generated the message. This parameter can be one of the following values:

Value	Meaning
MSGF_DDEMGR	The input event occurred while the Dynamic Data Exchange Management Library (DDEML) was waiting for a synchronous transaction to finish.
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.

Return Value

If the hook procedure processes the message, the return value must be a nonzero value. Otherwise, it must be zero.

Remarks

An application installs the hook procedure by specifying the WH_MSGFILTER hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

If an application that uses the DDEML and performs synchronous transactions must process messages before they are dispatched, it must use the WH_MSGFILTER hook.

MessageProc is a placeholder for the application-defined function name.

See Also

CallNextHookEx, SetWindowsHookEx, MSG


ModifyMenu

The ModifyMenu function changes an existing menu item. This function is used to specify the content, appearance, and behavior of the menu item.

BOOL ModifyMenu(

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
);
Parameters

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 following Remarks 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_MEASUREITEM or WM_DRAWITEM messages sent when the menu item is created or its appearance is updated.
MF_STRING	Contains a pointer to a null-terminated string (the default).
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

If 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, WM_DRAWITEM, WM_MEASUREITEM


ModifyWorldTransform

The ModifyWorldTransform function changes the world transformation for a device context using the specified mode.

BOOL ModifyWorldTransform(

HDC  hdc,	// handle of device context
CONST XFORM *  lpXform,	// address of transformation data
DWORD  iMode	// modification mode
);
Parameters

hdc

Specifies the device context.

lpXform

Points to an XFORM structure used to modify the world transformation for the given device context.

iMode

Specifies how the transformation data modifies the current world transformation. This parameter must be one of the following values:

Value	Description
MWT_IDENTITY	Resets the current world transformation by using the identity matrix. If this mode is specified, the XFORM structure pointed to by lpXform is ignored.
MWT_LEFTMULTIPLY	Multiplies the current transformation by the data in the XFORM structure. (The data in the XFORM structure becomes the left multiplicand, and the data for the current transformation becomes the right multiplicand.)
MWT_RIGHTMULTIPLY	Multiplies the current transformation by the data in the XFORM structure. (The data in the XFORM structure becomes the right multiplicand, and the data for the current transformation becomes the left multiplicand.)
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The ModifyWorldTransform function will fail unless graphics mode for the specified device context has been set to GM_ADVANCED by previously calling the SetGraphicsMode function. Likewise, it will not be possible to reset the graphics mode for the device context to the default GM_COMPATIBLE mode, unless world transform has first been reset to the default identity transform by calling SetWorldTransform or ModifyWorldTransform.

See Also

GetWorldTransform, SetWorldTransform, SetGraphicsMode, XFORM


mouse_event

The mouse_event function synthesizes mouse motion and button clicks.

VOID mouse_event(

DWORD  dwFlags,	// flags specifying various motion/click variants
DWORD  dx,	// horizontal mouse position or position change
DWORD  dy,	// vertical mouse position or position change
DWORD  cButtons,	// unused, reserved for future use, set to zero
DWORD  dwExtraInfo	// 32 bits of application-defined information
);
Parameters

dwFlags

A set of flag bits that specify various aspects of mouse motion and button clicking. The bits in this parameter can be any reasonable combination of the following values:

Value	Meaning
MOUSEEVENTF_ABSOLUTE	Specifies that the dx and dy parameters contain normalized absolute coordinates. If not set, those parameters contain relative data: the change in position since the last reported position. This flag can be set, or not set, regardless of what kind of mouse or mouse-like device, if any, is connected to the system. For further information about relative mouse motion, see the following Remarks section.
MOUSEEVENTF_MOVE	Specifies that movement occurred.
MOUSEEVENTF_LEFTDOWN	Specifies that the left button changed to down.
MOUSEEVENTF_LEFTUP	Specifies that the left button changed to up.
MOUSEEVENTF_RIGHTDOWN	Specifies that the right button changed to down.
MOUSEEVENTF_RIGHTUP	Specifies that the right button changed to up.
MOUSEEVENTF_MIDDLEDOWN	Specifies that the middle button changed to down.
MOUSEEVENTF_MIDDLEUP	Specifies that the middle button changed to up.
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.

Return Value

This function has no return value.

Remarks

If the mouse has moved, indicated by MOUSEEVENTF_MOVE being set, dx and dy hold information about that motion. The information is given as absolute or relative integer values.

If MOUSEEVENTF_ABSOLUTE value is specified, dx and dy contain normalized absolute coordinates between 0 and 65,535. The event procedure maps these coordinates onto the display surface. Coordinate (0,0) maps onto the upper-left corner of the display surface, (65535,65535) maps onto the lower-right corner.

If the MOUSEEVENTF_ABSOLUTE value is not specified, dx and dy specify relative motions from when the last mouse event was generated (the last reported position). Positive values mean the mouse moved right (or down); negative values mean the mouse moved left (or up).

Relative mouse motion is subject to the effects of the mouse speed and the two mouse threshold values. An end user sets these three values with the Mouse Tracking Speed slider of Control Panel's Mouse option. An application obtains and sets these values with the SystemParameters function. The operating system applies two tests to the specified relative mouse motion. If the specified distance along either the x or y axis is greater than the first mouse threshold value, and the mouse speed is not zero, the operating system doubles the distance. If the specified distance along either the x or y axis is greater than the second mouse threshold value, and the mouse speed is equal to two, the operating system doubles the distance that resulted from applying the first threshold test. It is thus possible for the operating system to multiply relatively-specified mouse motion along the x or y axis by up to four times.

The mouse_event function is used to synthesize mouse events by applications that need to do so. It is also used by applications that need to obtain more information from the mouse than its position and button state. For example, if a tablet manufacturer wants to pass pen-based information to its own applications, it can write a dynamic-link library (DLL) that communicates directly to the tablet hardware, obtains the extra information, and saves it in a queue. The DLL then calls mouse_event with the standard button and x/y position data, along with, in the dwExtraInfo parameter, some pointer or index to the queued extra information. When the application needs the extra information, it calls the DLL with the pointer or index stored in dwExtraInfo, and the DLL returns the extra information.

See Also

GetMessageExtraInfo


MouseProc

The MouseProc hook procedure is an application-defined or library-defined callback function the system calls whenever an application calls the GetMessage or PeekMessage function and there is a mouse message to be processed.

LRESULT CALLBACK MouseProc(

int  nCode,	// hook code
WPARAM  wParam,	// message identifier
LPARAM  lParam	// mouse coordinates
);
Parameters

nCode

Specifies a code the hook procedure uses to determine how to process the message. This parameter can be one of the following values:

Value	Meaning
HC_ACTION	The wParam and lParam parameters contain information about a mouse message.
HC_NOREMOVE	The wParam and lParam parameters contain information about a mouse message, and the mouse message has not been removed from the message queue. (An application called the PeekMessage function, specifying the PM_NOREMOVE flag.)
If nCode is less than zero, the hook procedure must pass the message to the CallNextHookEx function without further processing and should return the value returned by CallNextHookEx.

wParam

Specifies the identifier of the mouse message.

lParam

Points to a MOUSEHOOKSTRUCT structure.

Return Value

To enable the system to process the message, the return value must be zero. To discard the message, the return value must be a nonzero value.

Remarks

The hook procedure must not install a JournalPlaybackProc callback function.

An application installs the hook procedure by specifying the WH_MOUSE hook type and the address of the hook procedure in a call to the SetWindowsHookEx function.

MouseProc is a placeholder for the application-defined or library-defined function name.

See Also

CallNextHookEx, GetMessage, JournalPlaybackProc, MOUSEHOOKSTRUCT, PeekMessage, SetWindowsHookEx


MoveFile

The MoveFile function renames an existing file or a directory (including all its children).

BOOL MoveFile(

LPCTSTR  lpszExisting,	// address of name of the existing file
LPCTSTR  lpszNew	// address of new name for the file
);
Parameters

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.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The MoveFile function will move (rename) either a file or a directory (including all its children) either in the same directory or across directories. The one caveat is that the MoveFile function will fail on directory moves when the destination is on a different volume.

See Also

CopyFile, MoveFileEx


MoveFileEx

The MoveFileEx function renames an existing file.

BOOL MoveFileEx(

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
);
Parameters

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 lpszExisting. When moving a file, the destination can be on a different file system or drive. When moving a directory, the destination must be on the same drive. If fdwFlags specifies both MOVEFILE_REPLACE_EXISTING and MOVEFILE_DELAY_UNTIL_REBOOT, lpszNew can be NULL. In this case, the function registers the lpszExisting file to be deleted when the system reboots.

fdwFlags

A set of bit flags that specify how to move the file. You can specify any combination 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. Cannot be combined with the MOVEFILE_DELAY_UNTIL_REBOOT flag.
MOVEFILE_DELAY_UNTIL_REBOOT
	Windows NT only: The function does not move the file until the operating system is restarted. The system moves the file immediately after AUTOCHK is executed, but before creating any paging files. Consequently, this parameter enables the function to delete paging files from previous startups.
Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

An application cannot specify both MOVEFILE_DELAY_UNTIL_REBOOT and MOVEFILE_COPY_ALLOWED for fdwFlags. Function calls that do so will fail.

Windows NT only: If the fdwFlags parameter specifies MOVEFILE_REPLACE_EXISTING and MOVEFILE_DELAY_UNTIL_REBOOT, the function stores entries under the following registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\
Session Manager\FileRenameOperations

The system uses these registry entries to complete the operation at reboot.

See Also

CopyFile, DeleteFile, MoveFile


MoveMemory

The MoveMemory function moves a block of memory from one location to another.

VOID MoveMemory (

PVOID  Destination,	// address of move destination
CONST VOID *  Source,	// address of block to move
DWORD  Length	// size, in bytes, of block to move
);
Parameters

Destination

Points to the starting address of the destination of the move.

Source

Points to the starting address of the block of memory to move.

Length

Specifies the size, in bytes, of the block of memory to move.

Return Value

This function has no return value.

Remarks

The source and destination blocks may overlap.

See Also

CopyMemory, FillMemory, ZeroMemory


MoveTo

The MoveTo function is not implemented in the Win32 API. Win32-based applications should use the MoveToEx function.


MoveToEx

The MoveToEx function updates the current position to the specified point and optionally returns the previous position.

BOOL MoveToEx(

HDC  hdc,	// handle of device context
int  X,	// x-coordinate of new current position
int  Y,	// y-coordinate of new current position
LPPOINT  lpPoint	// address of old current position
);
Parameters

hdc

Identifies a device context.

X

Specifies the x-coordinate of the new position, in logical units.

Y

Specifies the y-coordinate of the new position, in logical units.

lpPoint

Points to a POINT structure in which the previous current position is stored. If this parameter is a NULL pointer, the previous position is not returned.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

The MoveToEx function affects all drawing functions.

See Also

AngleArc, LineTo, POINT, PolyBezierTo, PolylineTo


MoveWindow

The MoveWindow function changes the position and dimensions of the specified window. For a top-level window, the position and dimensions are relative to the upper-left corner of the screen. For a child window, they are relative to the upper-left corner of the parent window's client area.

BOOL MoveWindow(

HWND  hwnd,	// handle of window
int  x,	// horizontal position
int  y,	// vertical position
int  cx,	// width
int  cy,	// height
BOOL  fRepaint	// repaint flag
);
Parameters

hwnd

Identifies the window.

x

Specifies the new position of the left side of the window.

y

Specifies the new position of the top of the window.

cx

Specifies the new width of the window.

cy

Specifies the new height of the window.

fRepaint

Specifies whether the window is to be repainted. If this parameter is TRUE, the window receives a WM_PAINT message. If the parameter is FALSE, no repainting of any kind occurs. This applies to the client area, the nonclient area (including the title bar and scroll bars), and any part of the parent window uncovered as a result of moving a child window. If this parameter is FALSE, the application must explicitly invalidate or redraw any parts of the window and parent window that need redrawing.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

Remarks

If the fRepaint 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 fRepaint is FALSE, Windows places the WM_PAINT message in the message queue associated with the window. The message loop dispatches the WM_PAINT message only after dispatching all other messages in the queue.

MoveWindow sends WM_WINDOWPOSCHANGING, WM_WINDOWPOSCHANGED, WM_MOVE, WM_SIZE, and WM_NCCALCSIZE messages to the window.

See Also

SetWindowPos, UpdateWindow, WM_GETMINMAXINFO, WM_PAINT


MsgWaitForMultipleObjects

The MsgWaitForMultipleObjects function returns when one of the following occurs:

•	Either any one or all of the specified objects are in the signaled state.

•	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.

DWORD MsgWaitForMultipleObjects(

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
);
Parameters

cObjects

Specifies the number of object handles in the array pointed to by lphObjects. The maximum number of object handles is MAXIMUM_WAIT_OBJECTS minus one.

lphObjects

Points to an array of object handles. For a list of the object types whose handles can be specified, see the following Remarks section. The array can contain handles of objects of different types.

Windows NT: The handles must have SYNCHRONIZE access.

fWaitAll

Specifies the wait type. If TRUE, the function returns when 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.
Return Value

If the function succeeds, the return value indicates the event that caused the function to return. The successful return value is one of the following:

Value	Meaning
WAIT_OBJECT_0 to (WAIT_OBJECT_0 + 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.
If the function fails, the return valueis 0xFFFFFFFF. To get extended error information, call GetLastError.

Remarks

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, using 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.

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 signaled.

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 signaled

      result = MsgWaitForMultipleObjects(cObjects, lphObjects,

                                 FALSE, INFINITE, QS_ALLINPUT);

      // result tells us the type of event we have:

      // a message or a signaled handle

      // if there are one or more messages in the queue ...

      if (result == (WAIT_OBJECT_0 + cObjects)) {

         // 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 signaled

         // deal with that

         DoStuff (result - WAIT_OBJECT_0) ;

      } // end of else-clause

   } // end of the always while-loop

} // end of function

See Also

CreateEvent, CreateFile, CreateMutex, CreateProcess, CreateRemoteThread, CreateSemaphore, CreateThread, FindFirstChangeNotification, GetStdHandle, OpenEvent, OpenMutex, OpenProcess, OpenSemaphore, PulseEvent, ResetEvent, SetEvent, Sleep, WaitForMultipleObjects, WaitForMultipleObjectsEx, WaitForSingleObject


MulDiv

The MulDiv function multiplies two 32-bit values and then divides the 64-bit result by a third 32-bit value. The return value is rounded up or down to the nearest integer.

int MulDiv(

int  nMultiplicand,	// 32-bit signed multiplicand
int  nMultiplier,	// 32-bit signed multiplier
int  nDivisor	// 32-bit signed divisor
);
Parameters

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.

Return Value

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

Int32x32To64, UInt32x32To64


MultiByteToWideChar

The MultiByteToWideChar function maps a character string to a wide-character (Unicode) string. The character string mapped by this function is not necessarily from a multibyte character set.

int MultiByteToWideChar(

UINT  CodePage,	// code page
DWORD  dwFlags,	// character-type options
LPCSTR  lpMultiByteStr,	// address of string to map
int  cchMultiByte,	// number of characters in string
LPWSTR  lpWideCharStr,	// address of wide-character buffer
int  cchWideChar	// size of buffer
);
Parameters

CodePage

Specifies the code page to be used to perform the conversion. This parameter can be given the value of any codepage that is installed or available in the system. The following values may be used to specify one of the system default code pages:

Value	Meaning
CP_ACP	ANSI code page
CP_MACCP	Macintosh code page
CP_OEMCP	OEM code page
dwFlags

A set of bit flags that indicate whether to translate to precomposed or composite wide characters (if a composite form exists), whether to use glyph characters in place of control characters, and how to deal with invalid characters. You can specify a combination of the following flag constants:

Value	Meaning
MB_PRECOMPOSED	Always use precomposed characters — that is, characters in which a base character and a nonspacing character have a single character value. This is the default translation option. Cannot be used with MB_COMPOSITE.
MB_COMPOSITE	Always use composite characters — that is, characters in which a base character and a nonspacing character have different character values. Cannot be used with MB_PRECOMPOSED.
MB_ERR_INVALID_CHARS	If the function encounters an invalid input character, it fails and GetLastError returns ERROR_NO_UNICODE_TRANSLATION.
MB_USEGLYPHCHARS	Use glyph characters instead of control characters.
A composite character consists of a base character and a nonspacing character, each having different character values. A precomposed character has a single character value for a base/non-spacing character combination. In the character è, the e is the base character and the accent grave mark is the nonspacing character.

The function's default behavior is to translate to the precomposed form. If a precomposed form does not exist, the function attempts to translate to a composite form.

The flags MB_PRECOMPOSED and MB_COMPOSITE are mutually exclusive. The MB_USEGLYPHCHARS flag and the MB_ERR_INVALID_CHARS can be set regardless of the state of the other flags.

lpMultiByteStr

Points to the character string to be converted.

cchMultiByte

Specifies the size in bytes of the string pointed to by the lpMultiByteStr parameter. If this value is −1, the string is assumed to be null terminated and the length is calculated automatically.

lpWideCharStr

Points to a buffer that receives the translated string.

cchWideChar

Specifies the size, in wide characters, of the buffer pointed to by the lpWideCharStr parameter. If this value is zero, the function returns the required buffer size, in wide characters, and makes no use of the lpWideCharStr buffer.

Return Value

If the function succeeds, and cchWideChar is nonzero, the return value is the number of wide characters written to the buffer pointed to by lpWideCharStr.

If the function succeeds, and cchWideChar is zero, the return value is the required size, in wide characters, for a buffer that can receive the translated string.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes:

ERROR_INSUFFICIENT_BUFFER

ERROR_INVALID_FLAGS

ERROR_INVALID_PARAMETER

ERROR_NO_UNICODE_TRANSLATION

Remarks

The lpMultiByteStr and lpWideCharStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns the value ERROR_INVALID_PARAMETER.

The function fails if MB_ERR_INVALID_CHARS is set and it encounters an invalid character in the source string.  An invalid character is one that would translate to the default character if MB_ERR_INVALID_CHARS was not set, but is not the default character in the source string, or when a lead byte is found in a string and there is no valid trail byte for DBCS strings. When an invalid character is found, and MB_ERR_INVALID_CHARS is set, the function returns 0 and sets GetLastError with the error ERROR_NO_UNICODE_TRANSLATION.

See Also

WideCharToMultiByte


NDdeGetErrorString

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.

UINT NDdeGetErrorString (

UINT  uErrorCode,	// Error code to get string for
LPTSTR  lpszErrorString,	// buffer to hold error string
DWORD  cBufSize	// size of buffer
);
Parameters

uErrorCode

Error code to be converted.

lpszErrorString

Address of a buffer to accept the translated 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.

Return Value

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error code. If the lpszErrorString buffer is not large enough to accept the complete error string, and the string is truncated, the function returns the value NDDE_BUF_TOO_SMALL.


NDdeGetShareSecurity

The NDdeGetShareSecurity function is called to get the SECURITY_DESCRIPTOR associated with the DDE share. This is done usually for editing.

UINT NDdeGetShareSecurity(

LPTSTR  lpszServer,	// server to execute on
LPTSTR  lpszShareName,	// name of share to delete
SECURITY_INFORMATION  si,	// requested information
PSECURITY_DESCRIPTOR  pSD,	// address of SD buffer
DWORD  cbSD,	// size of SD buffer
LPDWORD  lpcbsdRequired	// address of required size for SD buffer
);
Parameters

lpszServer

Address of the server name on which the DSDM 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 the NDDE_BUF_TOO_SMALL error code.

cbSD

Specifies the size of the buffer provided and referenced by the pSD parameter to accept the retrieved security descriptor. It must be 0 if pSD is NULL.

lpcbsdRequired

Address of the variable into which the actual size of the retrieved security descriptor is stored. Must not be NULL.

Return Value

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString. If the pSD parameter was NULL, it returns NDDE_BUF_TOO_SMALL.

See Also

SECURITY_INFORMATION


NDdeGetTrustedShare

The NDdeGetTrustedShare function is called to retrieve the options associated with a currently "trusted" DDE share.

UINT NDdeGetTrustedShare (

LPTSTR  lpszServer,	// server to execute on
LPTSTR  lpszShareName,	// name of share to query
LPDWORD  lpdwTrustOptions,	// trust options in effect
LPDWORD  lpdwShareModId0,	// first word of share modify identifier
LPDWORD  lpdwShareModId1	// second word of share modify identifier
);
Parameters

lpszServer

Address of the server name on which the DSDM 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 identifier will be stored. Must not be NULL.

lpdwShareModId1

Address of a variable into which the second word of the trusted share modify identifier will be stored. Must not be NULL.

Return Value

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString.

Remarks

The trusted share modify identifier reflects the version of the DDE share in the NetDDE DSDM at the time the DDE share was initially promoted to trust status. The trusted share modify identifier is primarily used to purge obsolete trusted shares. However, the user does not need to purge obsolete trusted shares. The NetDDE Agent purges obsolete shares on the user's behalf.


NDdeIsValidAppTopicList

The NDdeIsValidAppTopicList function is called to validate an application and topic string ("AppName|TopicName") for proper syntax.

BOOL NDdeIsValidAppTopicList (

LPTSTR lpszTopic	// points to app and topic string
);
Parameters

lpszTopic

Address of the application and topic string  to validate. Must not be NULL.

Return Value

If lpszTopic has valid syntax, the return value is TRUE.

If the function fails, the return value is FALSE.


NDdeIsValidShareName

The NDdeIsValidShareName function is called to validate a share name for proper syntax.

BOOL NDdeIsValidShareName (

LPTSTR  lpszShare	// points to share name to validate
);
Parameters

lpszShare

Address of a share name to validate. Must not be NULL.

Return Value

If the share name has valid syntax, the return value is TRUE.

If the function fails, the return value is FALSE.


NDdeSetShareSecurity

The NDdeSetShareSecurity function is called to set the SECURITY_DESCRIPTOR associated with the DDE share. This is done usually after editing the DACL assigned to the DDE share.

UINT NDdeSetShareSecurity(

LPTSTR  lpszServer,	// server to execute on
LPTSTR  lpszShareName,	// name of share to delete
SECURITY_INFORMATION  si,	// type of information
PSECURITY_DESCRIPTOR  pSD	// address of security descriptor to set
);
Parameters

lpszServer

Address of the server name on which the DSDM will be modified.

lpszShareName

Address of the share name whose security descriptor is to be modified in the DSDM. This parameter 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.

Return Value

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString.

Remarks

To modify the SECURITY_DESCRIPTOR associated with a DDE share in the DSDM, the user must have appropriate privileges; for example, the share creator has such rights.

See Also

SECURITY_INFORMATION


NDdeSetTrustedShare

The NDdeSetTrustedShare function is called to promote the referenced DDE share to trusted status within the current user's context.

UINT NDdeSetTrustedShare (

LPTSTR  lpszServer,	// server to execute on
LPTSTR  lpszShareName,	// name of share to delete
DWORD  dwTrustOptions	// trust options to apply
);
Parameters

lpszServer

Address of the server name on which the DSDM will be modified.

lpszShareName

Address of the share name being 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.
Return Value

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString.

Remarks

If NDdeSetTrustedShare is called with dwTrustOptions set to 0, the trusted share loses its trusted status.


NDdeShareAdd

The NDdeShareAdd function is called to create and add a new DDE share to the NetDDE Share Database Manager (DSDM).

UINT NDdeShareAdd (

LPTSTR  lpszServer,	// server to execute on
UINT  nLevel,	// info level must be 2
PSECURITY_DESCRIPTOR  pSD,	// initial security descriptor
LPBYTE  lpBuffer,	// address of NDDESHAREINFO
DWORD  cBufSize	// size of supplied buffer
);
Parameters

lpszServer

Address of the server name on which the DSDM will be modified.

nLevel

Must always be 2.

pSD

Address of the SECURITY_DESCRIPTOR that will be associated with this share and against which access checks will be performed on subsequent initiates to this share. This parameter can optionally be NULL, in which case the DSDM creates a default SECURITY_DESCRIPTOR that grants "Full Control" to the CREATOR_OWNER and "Read and Link" to everyone.

lpBuffer

Address of the NDDESHAREINFO structure that defines the ApplicationTopic list associated with the DDE share being created as well as other parameters. This parameter must not be NULL.

cBufSize

Size of the structure identified by lpBuffer. It must not be 0.

Return Value

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString.

See Also

NDDESHAREINFO


NDdeShareDel

The NDdeShareDel function is called to delete a DDE share from the NetDDE DSDM.

UINT NDdeShareDel (

LPTSTR  lpszServer,	// server to execute on
LPTSTR  lpszShareName,	// name of share to delete
UINT  wReserved	// must be 0
);
Parameters

lpszServer

Address of the server name on which the DSDM will be modified.

lpszShareName

Address of the share name that is to be deleted from the DSDM. This parameter should not be NULL.

wReserved

Must be 0.

Return Value

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code which can be translated into a text error message by calling NDdeGetErrorString.

Remarks

To delete a DDE share from the DSDM, the user must have appropriate privileges. The share creator has delete rights.


NDdeShareEnum

The NDdeShareEnum function is called to list the available DDE shares in the NetDDE DSDM.

UINT NDdeShareEnum (

LPTSTR  lpszServer,	// server to execute on
UINT  nLevel,	// must be 0
LPBYTE  lpBuffer,	// pointer to buffer
DWORD  cBufSize,	// size of buffer
LPDWORD  lpnEntriesRead,	// number of names returned
LPDWORD  lpcbTotalAvailable	// number of bytes available
);
Parameters

lpszServer

Address of the server name on which the DSDM 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.

Return Value

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString. If the lpBuffer parameter is NULL, it returns NDDE_BUF_TOO_SMALL.


NDdeShareGetInfo

The NDdeShareGetInfo function is called to retrieve DDE share information from the NetDDE DSDM. This is usually done for editing.

UINT NDdeShareGetInfo (

LPTSTR  lpszServer,	// server to execute on
LPTSTR  lpszShareName,	// name of share
UINT  nLevel,	// info level must be 2
LPBYTE  lpBuffer,	// contains (NDDESHAREINFO) + data
DWORD  cBufSize,	// size of buffer
LPDWORD  lpnTotalAvailable,	// number of bytes available
LPWORD  lpnItems	// item mask for partial getinfo
);
Parameters

lpszServer

Address of the server name on which the DSDM 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.

Return Value

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString. If the lpBuffer parameter is NULL, it returns NDDE_BUF_TOO_SMALL.

See Also

NDDESHAREINFO structure


NDdeShareSetInfo

The NDdeShareSetInfo function is called to modify DDE share information stored in the NetDDE DSDM. This is usually done after editing.

UINT NDdeShareSetInfo (

LPTSTR  lpszServer,	// server to execute on
LPTSTR  lpszShareName,	// name of share
UINT  nLevel,	// information level must be 2
LPBYTE  lpBuffer,	// address of NDDESHAREINFO
DWORD  cBufSize,	// size of buffer
WORD  sParmNum	// parameter index
);
Parameters

lpszServer

Address of the server name on which the DSDM will be modified.

lpszShareName

Address of the share name whose information is to be modified in the DSDM. This parameter 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, that is, no partial edits are made. 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.

Return Value

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString.

See Also

NDDESHAREINFO


NDdeTrustedShareEnum

The NDdeTrustedShareEnumfunction lists the names of all network DDE shares that are trusted in the context of the calling process.

UINT NDdeTrustedShareEnum (

LPTSTR  lpszServer,	// server to execute on
UINT  nLevel,	// must be 0
LPBYTE  lpBuffer,	// pointer to buffer
DWORD  cBufSize,	// size of buffer
LPDWORD  lpnEntriesRead,	// number of names returned
LPDWORD  lpcbTotalAvailable	// number of bytes available
);
Parameters

lpszServer

Address of the server name on which the DSDM 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.

Return Value

If the function succeeds, the return value is NDDE_NO_ERROR.

If the function fails, the return value is an error code, which can be translated into a text error message by calling NDdeGetErrorString. If the lpBuffer parameter is NULL, it returns NDDE_BUF_TOO_SMALL.


NetAccessAdd

Note  The NetAccessAdd function works only when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) functions for Windows NT.

NetAccessAdd creates a new Access Control List (ACL) for a resource.

Security Requirements

Admin group membership is required to successfully execute NetAccessAdd.

NET_API_STATUS
NetAccessAdd (

LPTSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information provided. Must be 1.

buf

A pointer to a buffer containing the access information structure.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetAccessCheck

Note  The NetAccessCheck function works only when remoted to a downlevel system. Use Win32 (AccessCheck) function for Windows NT.

NetAccessCheck verifies that a user has permission to perform a specified operation on a particular resource.

Security Requirements

Admin group membership is required to successfully execute NetAccessCheck.

NET_API_STATUS
NetAccessCheck (

LPWSTR servername,
LPWSTR username,
LPWSTR resource,
DWORD operation,
LPDWORD result
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

username

A pointer to a Unicode string containing the name of the user to check for access to the resource.

resource

A pointer to a Unicode string containing the resource for which to check user permissions.

operation

Points to a DWORD specifying the type of access operation requested.

Symbolic constant	Value	Meaning
ACCESS_READ	0x01	Permission to read data from a resource and, by default, execute the resource.
ACCESS_WRITE	0x02	Permission to write data to the resource.
ACCESS_CREATE	0x04	Permission to create an instance of the resource (for example, a file); data can be written to the resource when creating it.
ACCESS_EXEC	0x08	Permission to execute the resource.
ACCESS_DELETE	0x10	Permission to delete the resource.
ACCESS_ATRIB	0x20	Permission to modify the resource's attributes (for example, the date and time a file was last modified).
ACCESS_PERM	0x40	Permission to modify the permissions (read, write, create, execute, and delete) assigned to a resource for a user, group, or application.
ACCESS_ALL	0x7F	Permission to read, write, create,execute, or delete a resource, or to modify attributes or permissions in which the user permissions for the specified resource are returned.
result

Points to a DWORD in which the result of the access check is returned.


NetAccessDel

Note  The NetAccessDel function works only when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) functions for Windows NT.

NetAccessDel deletes the access control list for a particular resource.

Security Requirements

Admin group membership or P permission for the resource is required to successfully execute NetAccessDel.

NET_API_STATUS
NetAccessDel (

LPTSTR servername,
LPTSTR resource
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

resource

A pointer to a Unicode string containing the name of the resource for which to remove the access control entry.


NetAccessEnum

Note  The NetAccessEnum function works only when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) functions for Windows NT.

NetAccessEnum retrieves information about each access permision record.

NetAccessEnum is being phased out and is available only at levels 0 and 1 for Windows networking. It is recommended that NetAccessEnum not be used because it is unlikely to be supported in future releases.

Security Requirements

NetAccessEnum does not require admin group membership to execute but will return only records for entries for which the user has 'P' permission if the caller does not have admin group membership.

NET_API_STATUS
NetAccessEnum (

LPTSTR servername,
LPTSTR BasePath,
DWORD Recursive,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resume_handle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

BasePath

A pointer to a Unicode string that contains a base path for the resources. A NULL pointer or NULL string means no base path is to be used. The path can be specified as a universal naming convention (UNC) path.

Recursive

A flag to enables or disable recursive searching. If Recursive is 0, NetAccessEnum returns entries only for the resource named as the base path by BasePath and for the resources directly below that base path. If Recursive is nonzero, NetAccessEnum returns entries for all access control lists (ACLs) that have BasePath at the beginning of the resource name.

level

Level of information required. Only 0 and 1 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resume_handle

On return, a resume handle is stored in the DWORD pointed to by resume_handle, and is used to continue an existing access search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.


NetAccessGetInfo

Note  The NetAccessGetInfo function works only when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) functions for Windows NT.

NetAccessGetInfo retrieves the access control information for a specific resource.

Security Requirements

Admin group membership or P permission is required to successfully execute NetAccessGetInfo.

NET_API_STATUS
NetAccessGetInfo (

LPTSTR servername,
LPTSTR resource,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

resource

A pointer to a Unicode string containing the name of the resource on which to return access control information.

level

Level of information required. 0 and 1 are valid.

bufptr

A pointer to the return information structure is returned in the address pointed to by bufptr.


NetAccessGetUserPerms

Note  The NetAccessGetUserPerms function works only when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) functions for Windows NT.

NetAccessGetUserPerms returns a specified user's or group's access permissions for a particular resource.

Security Requirements

Admin group membership or P permission for the resource is required to successfully execute NetAccessGetUserPerms.except when users request their own access permissions to a resource. In this case no special group membership is required.

NET_API_STATUS
NetAccessGetUserPerms (

LPTSTR servername,
LPTSTR UGname,
LPTSTR resource,
LPDWORD Perms
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

UGname

A pointer to a Unicode string containing the name of the user or group to query permissions for.

resource

A pointer to a Unicode string containing the resource for which to query user permissions.

Perms

Points to a DWORD in which the user permissions for the specified resource are returned.


NetAccessSetInfo

Note  The NetAccessSetInfo functions works only when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) functions for Windows NT.

NetAccessSetInfo changes the access control list for a resource.

Security Requirements

Admin group membership or P permission for the resource is required to successfully execute NetAccessSetInfo.

NET_API_STATUS
NetAccessSetInfo (

LPTSTR servername,
LPTSTR resource,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

resource

A pointer to a Unicode string containing the name of the resource for which the access information should be changed.

level

Level of information to set. Only 1 and 1002 are valid.

buf

A pointer to a buffer containing the access entry information.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetAlertRaise

NetAlertRaise notifies all registered clients that a particular event occurred.

Security Requirements

No special group membership is required to successfully execute NetAlertRaise.

NET_API_STATUS
NetAlertRaise (

LPTSTR AlertEventName,
LPVOID Buffer,
DWORD BufferSize
);
Parameters

AlertEventName

Points to a Unicode string that specifies which type of alert to raise.

Buffer

Points to the data to be sent to the clients listening for this alert. The data should consist of the STD_ALERT data structure followed by any additional alert data.

BufferSize

Specifies the size of the buffer in bytes.


NetAlertRaiseEx

NetAlertRaiseEx simplifies the raising of an admin alert.

Security Requirements

No special group membership is required to successfully execute NetAlertRaiseEx.

NET_API_STATUS
NetAlertRaiseEx (

LPTSTR AlertEventName,
LPVOID VariableInfo,
DWORD VariableInfoSize,
LPTSTR ServiceName
);
Parameters

AlertEventName

Points to a Unicode string that specifies which type of alert to raise.

VariableInfo

Information to put into the admin alert.

VariableInfoSize

Number of bytes of variable information.

ServiceName

Name of the service raising the admin alert.


NetApiBufferAllocate

NetApiBufferAllocate allocates ByteCount bytes of memory from the heap.

NET_API_STATUS
NetApiBufferAllocate (

DWORD ByteCount,
LPVOID * Buffer
);
Parameters

ByteCount

The number of bytes to allocate.

buffer

A pointer to the location to store the pointer to the allocated buffer.


NetApiBufferFree

NetApiBufferFree frees the memory allocated by NetApiBufferAllocate.

NET_API_STATUS
NetApiBufferFree (

LPVOID Buffer
);
Parameters

Buffer

A pointer to an API information buffer previously returned on an function call.


NetApiBufferReallocate

NetApiBufferReallocate changes the size of a buffer allocated with NetApiBufferAllocate.

NET_API_STATUS
NetApiBufferReallocate (

LPVOID OldBuffer,
DWORD NewByteCount,
LPVOID NewBuffer
);
Parameters

OldBuffer

A pointer to the buffer to reallocate.

NewByteCount

The new size of the buffer.

NewBuffer

A pointer to an API information buffer previously returned on an function call.


NetApiBufferSize

NetApiBufferSize returns the size in bytes of the buffer allocated via NetApiBufferAllocate.

NET_API_STATUS
NetApiBufferSize (

LPVOID buffer,
DWORD ByteCount
);
Parameters

buffer

A pointer to an API information buffer previously returned on an function call.

ByteCount

The size of the buffer.


NetAuditClear

NetAuditClear clears the audit log on a server and, optionally, saves the entries in a backup file.

Security Requirements

Admin group membership is required to successfully execute NetAuditClear.

NET_API_STATUS
NetAuditClear (

LPTSTR server,
LPTSTR backupfile ,
LPTSTR service
);
Parameters

server

Points to a Unicode string that contains the name of the server on which to execute NetAuditClear. A NULL pointer or NULL string specifies the local computer.

backupfile

Points to a Unicode string that contains a name for the optional backup file. The calling application must have create and write permissions for the path specified by backupfile, and the path must already exist. A NULL pointer specifies not to back up the audit log.

service

Points to a Unicode string that contains the name of the service that owns the desired audit log to which the operation is to be performed.


NetAuditRead

NetAuditRead reads from the audit log on a server.

Security Requirements

Admin or accounts, comm, print, or server operator group membership is required to successfully execute NetAuditRead.

NET_API_STATUS
NetAuditRead (

LPTSTR server,
LPTSTR service,
LPHLOG auditloghandle,
DWORD offset,
LPDWORD reserved1,
DWORD reserved2,
DWORD offsetflag,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD bytesread,
LPDWORD totalavailable
);
Parameters

server

Points to a Unicode string that contains the name of the server on which to execute NetAuditRead. A NULL pointer or NULL string specifies the local computer.

service

Points to a Unicode string that contains the name of the service that owns the desired audit log to which the operation is to be performed.

auditloghandle

Points to the handle for the audit log. An application calling NetAuditRead for the first time must initialize the audit log handle as follows. The most significant bit (MSB) is the leftmost bit; the least significant bit (LSB) is the rightmost bit. After the first call, each call to NetAuditRead must be given the value for the handle returned by the previous call.

auditloghandle	Value	xxx
4.19.2.1	(MSB) − 64	0
4.19.2.2	− 0 (LSB)	1
offset

Specifies the record offset at which to begin reading. This parameter is ignored unless bit 1 in the offsetflag parameter is set. If offsetflag bit 1 is set, offset is taken as an offset based on the record number (not bytes) at which the returned data should begin. Note that the record offset parameter is zero-based from both directions, depending upon the direction of the read. If reading backward, record 0 is the last record in the log. If reading forward, record 0 is the first record in the log.

reserved1

Reserved. Must be NULL.

reserved2

Reserved. Must be zero.

offsetflag

Specifies the open flags, as follows:

Bit(s)	Meaning
4.19.2.3	If 0, the log is read forward. If 1, the log is read backward and records are returned in the buffer in reverse chronological order (newest records first).
4.19.2.4	If 0, reading proceeds sequentially. If 1, reading proceeds from the nth record from the start of the log, where n is the offset parameter.
4.19.2.5	Reserved; must be 0.
bufptr

On return a pointer to the returned information is returned in the address pointed to by bufptr. After a successful read operation, this buffer contains a sequence of audit entries with the accompanying variable-length data structures.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

bytesread

On return the actual number of bytes read into the buffer is located in the DWORD pointed to by bytesread.

totalavailable

On return the total bytes available to be read from the log is located in the DWORD pointed to by totalavailable.


Netbios

The Netbios function interprets and executes the specified network control block (NCB).

UCHAR Netbios(

PNCB  pncb	// address of network control block
);
Parameters

pncb

Points to an NCB structure describing the network control block to process.

Return Value

For synchronous requests, the return value is the return code of the NCB structure. That value is also returned in the ncb_retcode member of the NCB structure.

There are two return value possibilities for accepted asynchronous requests. If the asynchronous command has already completed when Netbios returns to its caller, the return value is the return code of the NCB structure, just as if it were a synchronous NCB structure. If the asynchronous command is still pending when Netbios returns to its caller, the return value is zero.

If the address specified by the pncb parameter is invalid, the return value is NRC_BADNCB.

Remarks

Netbios is primarily for applications written for the IBM NetBIOS system that need to be ported to Windows. Applications that do not have this requirement typically use other interfaces, such as mailslots and named pipes, instead of Netbios.

Netbios contains extensions to the standard IBM NetBIOS 3.0 specification to allow POST routines to be called from C and to operate efficiently in the Windows environment.

When an asynchronous network control block finishes and the ncb_post member is nonzero, the routine specified in ncb_post is called with a single parameter of type PNCB. This parameter contains the address of the finishing network control block. (In the standard IBM NetBIOS 3.0, the address of the network control block is supplied in a nonportable interface.)

Another extension to the NCB structure is a handle of an event (the ncb_event member). The event is set to the nonsignaled state by the system when an asynchronous NetBIOS command is accepted, and it is set to the signaled state when the asynchronous NetBIOS command finishes.

Using ncb_event to submit asynchronous requests requires fewer system resources than using ncb_post. Also, when ncb_event is nonzero, the pending request is canceled if the thread terminates before the request is processed. This is not true for requests sent by using ncb_post.

Only manual reset events should be used with Netbios. A specified event should not be associated with more than one active asynchronous NetBIOS command.

See Also

NCB


NetConfigGet

NetConfigGet retrieves the value of a single specified entry for a particular component on the local computer or on a remote server.

Security Requirements

Admin or accounts, comm, print, or server operator group membership is required to successfully execute NetConfigGet on a remote server.

NET_API_STATUS
NetConfigGet (

LPTSTR server,
LPTSTR component,
LPTSTR parameter,
LPBYTE * bufptr
);
Parameters

server

Points to a Unicode string that contains the name of the server on which to execute NetConfigGet. A NULL pointer or NULL string specifies the local computer.

component

Points to a Unicode string that specifies which configuration component to search.

parameter

Points to a Unicode string that specifies the entry for the component specified whose value is to be returned.

bufptr

On return a pointer to the returned information is returned in the address pointed to by bufptr.


NetConfigGetAll

NetConfigGetAll retrieves all the configuration information for a given component on a local or a remote computer.

Security Requirements

Admin or account, comm, print, or server operator group membership is required to successfully execute NetConfigGetAll on a remote server.

NET_API_STATUS
NetConfigGetAll (

LPTSTR server,
LPTSTR component,
LPBYTE * bufptr
);
Parameters

server

Points to a Unicode string that contains the name of the server on which to execute NetConfigGet. A NULL pointer or NULL string specifies the local computer.

component

Points to a Unicode string that specifies which configuration component to search.

bufptr

On return a pointer to the returned information is returned in the address pointed to by bufptr.


NetConfigSet

NetConfigSet sets the value of a single specified entry for a particular component on the local computer or on a remote server.

Security Requirements

Admin or server operator group membership is required to successfully execute NetConfigSet on a remote server.

NET_API_STATUS
NetConfigSet (

LPTSTR server,
LPTSTR reserved1,
LPTSTR component,
DWORD level,
DWORD reserved2,
LPBYTE buf,
DWORD reserved3
);
Parameters

server

Points to a Unicode string that contains the name of the server on which to execute NetConfigSet. A NULL pointer or NULL string specifies the local computer.

reserved1

Reserved. Must be NULL.

component

Points to a Unicode string that specifies which configuration component to set.

level

Information level of request. Must be zero.

reserved2

Reserved. Must be zero.

buf

Buffer containing a CONFIG_INFO_0 structure.

reserved3

Reserved. Must be zero.


NetConnectionEnum

NetConnectionEnum lists all connections made to a shared resource on the server or all connections established from a particular computer. If there is more than one user using this connection, then it is possible to get more than one structure for the same connection, but with a different user name. The NetConnectionEnum function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetEnumResource function.

Security Requirements

Admin or server, print, or comm operator group membership is required to successfully execute NetConnectionEnum.

NET_API_STATUS
NetConnectionEnum (

LPTSTR servername,
LPTSTR qualifier,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resumehandle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

qualifier

A pointer to a Unicode string containing a share name or computer name for the connections of interest. If it is a share name, then all the connections made to that share name are listed. If it is a computer name (for example, it starts with two backslash characters), then NetConnectionEnum lists all connections made from that computer to the server specified.

level

Level of information required. 0 and 1 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Prefered maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resume_handle

On return, a resume handle is stored in the DWORD pointed to by resume_handle, and is used to continue an existing connection search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.


NetErrorLogClear

NetErrorLogClear clears the error log and optionally saves the entries in a backup file.

Security Requirements

Admin group membership is required to successfully execute NetErrorLogClear on a remote server.

NET_API_STATUS
NetErrorLogClear (

LPTSTR server,
LPTSTR backupfile,
LPBYTE reserved
);
Parameters

server

Points to a Unicode string that contains the name of the server on which to execute NetErrorLogClear. A NULL pointer or NULL string specifies the local computer.

backupfile

Points to a Unicode string that assigns a name for an optional backup file. The calling application must have write permission for the path specified by backupfile. A NULL pointer indicates not to back up the error log.

reserved

Reserved. Must be NULL.


NetErrorLogRead

NetErrorLogRead reads from the specified error log.

Security Requirements

No special group membership is required to successfully execute NetErrorLogRead.

NET_API_STATUS
NetErrorLogRead (

LPTSTR server,
LPTSTR reserved1,
LPHLOG errloghandle,
DWORD offset,
LPDWORD reserved2,
DWORD reserved3,
DWORD offsetflag,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD bytesread,
LPDWORD totalbytes
);
Parameters

server

Points to a Unicode string that contains the name of the server on which to execute NetErrorLogClear. A NULL pointer or NULL string specifies the local computer.

reserved1

Reserved. Must be NULL.

errloghandle

Points to the error log handle. An application calling NetErrorLogRead for the first time must initialize the 128-bit error log handle.

offset

Specifies the record offset at which to begin reading. This parameter is ignored unless bit 1 of offsetflag is set. If used, offset is taken as an offset of the record number (not bytes) at which to begin reading. Note that the record offset parameter is zero-based from both directions, depending upon the direction it is read.

reserved2

Reserved. Must be NULL.

reserved3

Reserved. Must be zero.

offsetflag

Specifies the open flags, bitmapped as follows:

Bit(s)	Value
4.16.2.1	If 0, the log is read forward. If 1, the log is read backward and records are returned in reverse chronological order.
4.16.2.2	If 0, the read proceeds normally (sequentially). If 1, the read proceeds from the nth record from the start of the log, where n is the offset parameter.
4.16.2.3	Reserved; must be 0.
bufptr

On return a pointer to the return information buffer is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

bytesread

On return the actual number of bytes read into the buffer is located in the DWORD pointed to by bytesread.

totalbytes

On return the total bytes available to be read from the log is located in the DWORD pointed to by totalbytes.


NetFileClose

NetFileClose forces a resource to close. This function can be used when an error prevents closure by other means.

Security Requirements

Admin or server operator group membership is required to successfully execute NetFileClose.

NET_API_STATUS
NetFileClose (

LPTSTR servername,
DWORD fileid
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

fileid

The file identifier of the opened resource instance to be closed.


NetFileEnum

NetFileEnum supplies information about some or all open files on a server, allowing the user to supply a resume handle and get required information through repeated calls to the function.

Security Requirements

Admin or server operator group membership is required to successfully execute NetFileEnum.

NET_API_STATUS
NetFileEnum (

LPTSTR servername,
LPTSTR basepath,
LPTSTR username,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resume_handle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

basepath

A pointer to a Unicode string containing a qualifier for the returned information. If NULL then all open resources are enumerated, else only resources that have basepath as a prefix are enumerated. A prefix is the path component up to a back-slash.

username

A pointer to a Unicode string that specifies the name of the user. If not NULL, username serves as a qualifier to the enumeration. The files returned are limited to those that have user names matching the qualifier. If username is NULL, no user-name qualifier is used.

level

Level of information required. 2 and 3 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Prefered maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resume_handle

On return, a resume handle is stored in the DWORD pointed to by resume_handle, and is used to continue an existing file search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.


NetFileGetInfo

NetFileGetInfo retrieves information about a particular opening of a server resource.

Security Requirements

Admin or server operator group membership is required to successfully execute NetFileGetInfo.

NET_API_STATUS
NetFileGetInfo (

LPTSTR servername,
DWORD fileid,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

fileid

The file identifier of the open resource to return information on. The fileid value must be that returned in a previous enumeration call.

level

Level of information required. 2 and 3 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.


NetGetDCName

NetGetDCName returns the name of the Primary Domain Controller for the specified domain.

Security Requirements

No special group membership is required to successfully execute NetGetDCName.

NET_API_STATUS
NetGetDCName (

LPWSTR servername,
LPWSTR domainname,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

domainname

A pointer to a Unicode string containing the name of the domain. A NULL pointer or string indicates that the name of the domain controller for the primary domain is to be returned.

bufptr

A pointer to the buffer containing the domain controller name is returned in the address pointed to by bufptr.


NetGroupAdd

NetGroupAdd creates a global group in the security database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetGroupAdd.

NET_API_STATUS
NetGroupAdd (

LPWSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information provided. Must be 0 1, or 2.

buf

A pointer to a buffer containing the global group information structure.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetGroupAddUser

NetGroupAddUser gives an existing user account membership in an existing global group.

Security Requirements

Admin or account operator group membership is required to successfully execute NetGroupAddUser.

NET_API_STATUS
NetGroupAddUser (

LPWSTR servername,
LPWSTR GroupName,
LPWSTR username
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

GroupName

A pointer to a Unicode string containing the name of the global group to which the user is to be given membership.

Username

A pointer to a Unicode string containing the name of the user to be given global group membership.


NetGroupDel

NetGroupDel deletes a global group account from the accounts database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetGroupDel.

NET_API_STATUS
NetGroupDel (

LPWSTR servername,
LPWSTR groupname
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the global group account to delete.


NetGroupDelUser

NetGroupDelUser removes a user from a particular global group in the user account database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetGroupDelUser.

NET_API_STATUS
NetGroupDelUser (

LPWSTR servername,
LPWSTR GroupName,
LPWSTR Username
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

GroupName

A pointer to a Unicode string containing the name of the global group from which the user membership is to be removed.

Username

A pointer to a Unicode string containing the name of the user to remove from the global group.


NetGroupEnum

NetGroupEnum retrieves information about each global group account.

Security Requirements

Admin or account operator group membership is required to successfully execute NetGroupEnum.

NET_API_STATUS
NetGroupEnum (

LPWSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resume_handle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. 0 and 1 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resume_handle

On return, a resume handle is stored in the DWORD pointed to by resume_handle, and is used to continue an existing global group search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.


NetGroupGetInfo

NetGroupGetInfo retrieves information about a particular global group account on a server.

Security Requirements

Admin or account operator group membership is required to successfully execute NetGroupGetInfo.

NET_API_STATUS
NetGroupGetInfo (

LPWSTR servername,
LPWSTR groupname,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the global group account to return information on.

level

Level of information required. 0, 1, and 2 are valid.

bufptr

A pointer to the return information structure is returned in the address pointed to by bufptr.


NetGroupGetUsers

NetGroupGetUsers retrieves a list of the members of a particular global group in the user account database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetGroupGetUsers except when the request is made by a user who has membership in the specified global group, in which case no special group membership is required.

NET_API_STATUS
NetGroupGetUsers (

LPWSTR servername,
LPWSTR groupname,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD ResumeHandle
);
Parameters

servername

pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the global group whose members are to be listed.

level

Level of information required. Only 0 and 1 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

ResumeHandle

On return, a resume handle is stored in the DWORD pointed to by ResumeHandle, and is used to continue an existing usergroup search. The handle should be zero on the first call and left unchanged for subsequent calls. If ResumeHandle is NULL, then no resume handle is stored.


NetGroupSetInfo

NetGroupSetInfo sets the parameters of a global group account.

Security Requirements

Admin or account operator group membership is required to successfully execute NetGroupSetInfo.

NET_API_STATUS
NetGroupSetInfo (

LPWSTR servername,
LPWSTR groupname,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the global group account to set information on.

level

Level of information to set. Only 0, 1, and 2 are valid.

buf

A pointer to a buffer containing the global group information.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetGroupSetUsers

NetGroupSetUsers sets the global group membership for the specified global group. Each user specified is made a member of the global group. Users that are not specified but are currently members of the global group will have their membership revoked.

Security Requirements

Admin or account operator group membership is required to successfully execute NetGroupSetUsers on a remote server.

NET_API_STATUS
NetGroupSetUsers (

LPWSTR servername,
LPWSTR groupname,
DWORD level,
LPBYTE buf,
DWORD totalentries
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the global group to which the specified users belong.

level

Level of information supplied. Only 0 is valid.

buf

Points to the buffer in which the data to be set is stored. This data consists of a sequence of _GROUP_USERS_INFO_0 data structures.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.


NetLocalGroupAdd

NetLocalGroupAdd creates a local group in the security database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetLocalGroupAdd.

NET_API_STATUS
NetLocalGroupAdd (

LPWSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information provided. Must be 0 or 1.

buf

A pointer to a buffer containing the local group information structure.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetLocalGroupAddMember

NetLocalGroupAddMember gives an existing user account or global group membership in an existing local group.

Security Requirements

Admin or account operator group membership is required to successfully execute NetLocalGroupAddMember.

NET_API_STATUS
NetLocalGroupAddMember (

LPWSTR servername,
LPWSTR groupname,
PSID membersid
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the local group to which the user or global group is to be given membership.

membersid

A pointer to the SID of a user or global group from the local, primary, or trust domains to be given local group membership.


NetLocalGroupDel

NetLocalGroupDel deletes a local group account and all its members from the accounts database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetLocalGroupDel.

NET_API_STATUS
NetLocalGroupDel (

LPWSTR servername,
LPWSTR groupname
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the local group account to delete.


NetLocalGroupDelMember

NetLocalGroupDelMember removes a member from a particular local group in the security database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetLocalGroupDelMember.

NET_API_STATUS
NetLocalGroupDelMember (

LPWSTR servername,
LPWSTR groupname,
PSID membersid
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the local group from which the user membership is to be removed.

membersid

A pointer to a SID of a user or global group to remove from the local group.


NetLocalGroupEnum

NetLocalGroupEnum retrieves information about each local group account.

Security Requirements

Admin or account operator group membership is required to successfully execute NetLocalGroupEnum.

NET_API_STATUS
NetLocalGroupEnum (

LPWSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resumehandle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. 0 and 1 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resumehandle

On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing local group search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, then no resume handle is stored.


NetLocalGroupGetInfo

NetLocalGroupGetInfo retrieves information about a particular local group account on a server.

Security Requirements

Admin or account operator group membership is required to successfully execute NetLocalGroupGetInfo.

NET_API_STATUS
NetLocalGroupGetInfo (

LPWSTR servername,
LPWSTR groupname,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the local group account to return information on.

level

Level of information required. 0 and 1 are valid.

bufptr

A pointer to the return information structure is returned in the address pointed to by bufptr.


NetLocalGroupGetMembers

NetLocalGroupGetMembers retrieves a list of the members of a particular local group in the security database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetLocalGroupGetMembers except when the request is made by a user who has membership in the specified local group in which case no special group membership is required.

NET_API_STATUS
NetLocalGroupGetMembers (

LPWSTR servername,
LPWSTR localgroupname,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resumehandle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

localgroupname

A pointer to a Unicode string containing the name of the local group whose members are to be listed.

level

Level of information required. Levels 0 and 1 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Prefered maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resumehandle

On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing usergroup search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, then no resume handle is stored.


NetLocalGroupSetInfo

NetLocalGroupSetInfo sets the parameters of a local group.

Security Requirements

Admin or account operator group membership is required to successfully execute NetLocalGroupSetInfo.

NET_API_STATUS
NetLocalGroupSetInfo (

LPWSTR servername,
LPWSTR groupname,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the local group account to set information on.

level

Level of information to set. 0, 1, and 1002 are valid.

buf

A pointer to a buffer containing the local group information.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetLocalGroupSetMembers

NetLocalGroupSetMembers sets the local group membership for the specified local group. Each user or global group specified is made a member of the local group. Users or global groups that are not specified but are currently members of the local group will have their membership revoked.

Security Requirements

Admin or account operator group membership is required to successfully execute NetLocalGroupSetMembers on a remote server.

NET_API_STATUS
NetLocalGroupSetMembers (

LPWSTR servername,
LPWSTR groupname,
DWORD level,
LPBYTE buf,
DWORD totalentries
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

groupname

A pointer to a Unicode string containing the name of the local group to which the specified users or global groups belong.

level

Level of information supplied. Only 0 is valid.

buf

Points to the buffer in which the data to be set is stored. This data consists of a sequence of LOCALGROUP_MEMBERS_INFO_0 data structures.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.


NetMessageBufferSend

NetMessageBufferSend sends a buffer of information to a registered message alias.

Security Requirements

No special group membership is required to execute NetMessage buffer send locally. Admin, accounts, print, or server operator group membership is required to successfully execute NetMessageBufferSend on a remote server.

NET_API_STATUS
NetMessageBufferSend (

LPTSTR servername,
LPTSTR msgname,
LPTSTR fromname,
LPBYTE buf,
DWORD buflen
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

msgname

A pointer to a Unicode string containing the message name to which the message buffer should be sent.

fromname

A pointer to a Unicode string containing the message name sending the information. fromname is a new parameter for Windows networking. This parameter is needed for sending alerts from the computer name rather than the logged on user. If a NULL is specified the message is send from the logged on user as with LAN Manager 2.x.

buf

A pointer to a buffer of message text.

buflen

The length in bytes of the message text in buf.


NetMessageNameAdd

NetMessageNameAdd registers a message alias in the message name table. NetMessageNameAdd requires that the Messenger service be started.

Security Requirements

Admin group membership is required to successfully execute NetMessageNameAdd on a remote server.

NET_API_STATUS
NetMessageNameAdd (

LPTSTR servername,
LPTSTR msgname
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

msgname

A pointer to a Unicode string of limit 15 characters containing the message name to be added.

Note  The forward action flag from the LAN Manager 2.x NetMessageNameAdd is no longer a parameter because message forwarding is no longer supported. If the NetMessageNameAdd function detects that a forwarded version of msgname exists on the network, the function will fail with error NERR_Already_Exists.


NetMessageNameDel

NetMessageNameDel deletes a message alias from the table of message aliases on a computer. NetMessageNameDel requires that the Messenger service be started.

Security Requirements

Admin group membership is required to successfully execute NetMessageNameDel on a remote server.

NET_API_STATUS
NetMessageNameDel (

LPTSTR servername,
LPTSTR msgname
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

msgname

A pointer to a Unicode string of limit 15 characters containing the message name to be deleted.


NetMessageNameEnum

NetMessageNameEnum lists the message aliases that will receive messages on a specified computer. NetMessageNameEnum requires that the Messenger service be started.

Security Requirements

Admin group membership is required to successfully execute NetMessageNameEnum on a remote server.

NET_API_STATUS
NetMessageNameEnum (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resume_handle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. 0 and 1 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Prefered maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resume_handle

On return, a resume handle is stored in the DWORD pointed to by resume_handle, and is used to continue an existing message name search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.


NetMessageNameGetInfo

NetMessageNameGetInfo retrieves information about a particular message alias in the message name table. NetMessageNameGetInfo requires that the Messenger service be started.

Security Requirements

Admin group membership is required to successfully execute NetMessageNameGetInfo on a remote server.

NET_API_STATUS
NetMessageNameGetInfo (

LPTSTR servername,
LPTSTR msgname,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

msgname

A pointer to a Unicode string containing the message name to return information on.

level

Level of information required. 0 and 1 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.


NetRemoteTOD

The remote time-of-day information is available at one information level:

typedef struct _TIME_OF_DAY_INFO {
    DWORD    tod_elapsedt;
    DWORD    tod_msecs;
    DWORD    tod_hours;
    DWORD    tod_mins;
    DWORD    tod_secs;
    DWORD    tod_hunds;
    LONG     tod_timezone;
    DWORD    tod_tinterval;
    DWORD    tod_day;
    DWORD    tod_month;
    DWORD    tod_year;
    DWORD    tod_weekday;
} TIME_OF_DAY_INFO, *PTIME_OF_DAY_INFO, *LPTIME_OF_DAY_INFO;

NetRemoteTOD returns a server's time of day.

Security Requirements

No special group membership is required to successfully execute NetRemoteTOD.

NET_API_STATUS
NetRemoteTOD (

LPTSTR UncServerName,
LPBYTE * BufferPtr
);
Parameters

UncServerName

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

BufferPtr

On return a pointer to the return information structure is returned in the address pointed to by BufferPtr.


NetReplExportDirAdd

NetReplExportDirAdd registers an existing directory in the export path to be replicated. The default values for locktime and lockcount (both 0) are assumed.

Security Requirements

Admin or server operator group membership is required to successfully execute NetReplExportDirAdd.

NET_API_STATUS
NetReplExportDirAdd (

LPTSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information to add. Only level 1 is valid.

buf

A pointer to a buffer containing the directory control information structure.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetReplExportDirDel

NetReplExportDirDel deregisters a replicated directory.

Security Requirements

Admin or server operator group membership is required to successfully execute NetReplExportDirDel.

NET_API_STATUS
NetReplExportDirDel (

LPTSTR servername,
LPTSTR dirname
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

dirname

A pointer to a null-terminated Unicode string containing the name of a replicated directory to deregister.


NetReplExportDirEnum

NetReplExportDirEnum lists the replicated directories in the export path.

Security Requirements

No special group membership is required to successfully execute NetReplExportDirEnum.

NET_API_STATUS
NetReplExportDirEnum (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resumehandle
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information to return. Levels 0,1, and 2 are valid.

bufptr

On return, an array of the specified information structure is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes). A value of 0xFFFFFFFF indicates that all available entries should be returned.

entriesread

On return, the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return, the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resumehandle

On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing use search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, then no resume handle is stored.


NetReplExportDirGetInfo

NetReplExportDirGetInfo retrieves a replicated directory control information.

Security Requirements

No special group membership is required to successfully execute NetReplExportDirGetInfo.

NET_API_STATUS
NetReplExportDirGetInfo (

LPTSTR servername,
LPTSTR dirname,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

dirname

A pointer to a null-terminated Unicode string containing the directory name to return control information about.

level

Level of information to return. Levels 0, 1, and 2 are valid.

bufptr

On return a pointer to the return information structure is written in the address pointed to by bufptr.


NetReplExportDirLock

NetReplExportDirLock locks a replicated directory so that replication from it can be suspended. This function increments the lock reference count for the specified directory.

Security Requirements

Admin or server operator group membership is required to successfully execute NetReplExportDirLock.

NET_API_STATUS
NetReplExportDirLock (

LPTSTR servername,
LPTSTR dirname
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

dirname

A pointer to a null-terminated Unicode string containing the directory name to lock.


NetReplExportDirSetInfo

NetReplExportDirSetInfo modifies the control information of a replicated directory.

Security Requirements

Admin or server operator group membership is required to successfully execute NetReplExportDirSetInfo.

NET_API_STATUS
NetReplExportDirSetInfo (

LPTSTR servername,
LPTSTR dirname,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

dirname

A pointer to a null-terminated Unicode string containing the directory name to return control information about.

level

Level of information to set. Levels 1, 1000, and 1001 are valid.

buf

A pointer to a buffer containing the control information structure that corresponds to the specified level.

parm_err

Optional pointer to a DWORD to return the identifier of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetReplExportDirUnlock

NetReplExportDirUnlock unlocks a directory so that replication from it can resume. This function decrements the lock reference count for the specified directory.

Security Requirements

Admin or server operator group membership is required to successfully execute NetReplExportDirUnlock.

NET_API_STATUS
NetReplExportDirUnlock (

LPTSTR servername,
LPTSTR dirname,
DWORD unlockforce
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

dirname

A pointer to a null-terminated Unicode string containing the directory name to unlock.

unlockforce

A value that indicates the force level to unlock the directory.

Force levels:

REPL_UNLOCK_NOFORCE

Unlocks the directory by decrementing the lock reference count. The lock reference count may or may not return to 0, so the directory could still be locked.

REPL_UNLOCK_FORCE

Unlocks the directory completely by removing all outstanding locks on the directory. The lock reference count is set to 0.


NetReplGetInfo

NetReplGetInfo retrieves the Replicator service configuration information.

Security Requirements

No special group membership is required to successfully execute NetReplGetInfo.

NET_API_STATUS
NetReplGetInfo (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. Only level 0 is valid.

bufptr

On return a pointer to the return information structure is written in the address pointed to by bufptr.


NetReplImportDirAdd

NetReplImportDirAdd registers an existing directory in the import path to receive replication from a master.

Security Requirements

Admin or replicator group membership is required to successfully execute NetReplImportDirAdd.

NET_API_STATUS
NetReplImportDirAdd (

LPTSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information to add. Only level 0 is valid.

buf

A pointer to a buffer containing the directory name.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetReplImportDirDel

NetReplImportDirDel deregisters directory so that it no longer receives updates from the master. Note that this function does not actually delete the directory from the file system. Also, the directory may be automatically re-registered by the Replicator service at any time. To prevent importing of a directory that is being exported by some Replicator service, use the NetReplImportDirLock function instead.

Security Requirements

Admin or replicator group membership is required to successfully execute NetReplImportDirDel.

NET_API_STATUS
NetReplImportDirDel (

LPTSTR servername,
LPTSTR dirname
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

dirname

A pointer to a null-terminated Unicode string containing the name of a replicated directory to deregister.


NetReplImportDirEnum

NetReplImportDirEnum lists the replicated directories in the import path.

Security Requirements

No special group membership is required to successfully execute NetReplImportDirEnum.

NET_API_STATUS
NetReplImportDirEnum (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resumehandle
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information to return. Levels 0 or 1 are valid.

bufptr

On return, an array of the specified information structure is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes). A value of 0xFFFFFFFF indicates that all available entries should be returned.

entriesread

On return, the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return, the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resumehandle

On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing use search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, then no resume handle is stored.


NetReplImportDirGetInfo

NetReplImportDirGetInfo retrieves the status information on a client replicated directory.

Security Requirements

No special group membership is required to successfully execute NetReplImportDirGetInfo.

NET_API_STATUS
NetReplImportDirGetInfo (

LPTSTR servername,
LPTSTR dirname,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

dirname

A pointer to a null-terminated Unicode string containing the directory name to return control information about.

level

Level of information to return. Levels 0 and 1 are valid.

bufptr

On return a pointer to the return information structure is written in the address pointed to by bufptr.


NetReplImportDirLock

NetReplImportDirLock locks a replicated directory so that replication to it can be suspended. This function increments the lock reference count for the specified directory.

Security Requirements

Admin or replicator group membership is required to successfully execute NetReplImportDirLock.

NET_API_STATUS
NetReplImportDirLock (

LPTSTR servername,
LPTSTR dirname
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

dirname

A pointer to a null-terminated Unicode string containing the directory name to lock.


NetReplImportDirUnlock

NetReplImportDirUnlock unlocks a directory so that replication to it can resume. This function decrements the lock reference count for the specified directory.

Security Requirements

Admin or replicator group membership is required to successfully execute NetReplImportDirUnlock.

NET_API_STATUS
NetReplImportDirUnlock (

LPTSTR servername,
LPTSTR dirname,
DWORD unlockforce
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

dirname

A pointer to a null-terminated Unicode string containing the directory name to unlock.

unlockforce

A value that indicates the force level to unlock the directory.

Force levels:

REPL_UNLOCK_NOFORCE

Unlocks the directory by decrementing the lock reference count. The lock reference count may or may not return to 0, so the directory could still be locked.

REPL_UNLOCK_FORCE

Unlocks the directory completely by removing all outstanding locks on the directory. The lock reference count is set to 0.


NetReplSetInfo

NetReplSetInfo modifies the Replicator service configuration information.

Security Requirements

Admin or server operator group membership is required to successfully execute NetReplSetInfo.

NET_API_STATUS
NetReplSetInfo (

LPTSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a null-terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information to set 0, 1000, 1001, 1002, and 1003 are valid levels.

buf

A pointer to a buffer containing the configuration information structure that corresponds to the specified level.

parm_err

Optional pointer to a DWORD to return the identifier of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetScheduleJobAdd

NetScheduleJobAdd submits a job to run at a computer at a specified time and date in future. NetScheduleJobAdd requires that the Schedule service be started at computer where job is submitted to.

Security Requirements

Admin group membership is required to successfully execute NetScheduleJobAdd on a remote server.

NET_API_STATUS
NetScheduleJobAdd (

LPWSTR Servername,
LPBYTE Buffer,
LPDWORD JobId
);
Parameters

Servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

Buffer

A pointer to a buffer containing AT_INFO data structure describing job to be submitted.

JobId

A pointer to a job identifier for a newly submitted job. This entry is valid only if function returns success.

By choosing values in AT_INFO appropriately one may submit jobs with different types of execution periodicity. If DaysOfMonth and DaysOfWeek are both zero, then job will be executed only once, the first time JobTime at server is reached. After being executed, the job will be deleted.

If one sets bits in DaysOfMonth and/or DaysOfWeek, but does not set the bit flag JOB_RUN_PERIODICALLY, a job will execute at JobTime once for each day listed in days bitmasks. After each execution, the corresponding bit in days bitmasks will be cleared. Once the last bit in days bitmasks is cleared, the job will be deleted.

If one sets bits in DaysOfMonth and/or DaysOfWeek, and at the same time sets the bit flag JOB_RUN_PERIODICALLY, a job will execute at JobTime whenever a day with corresponding bit in days bitmasks is reached. This job is thus executed periodically and does not get deleted as a result of repeated executions. The only way to delete this job is by an explicit call to NetScheduleJobDel( ).


NetScheduleJobDel

NetScheduleJobDel deletes a range of jobs queued to run at a computer. NetScheduleJobDel requires that the Schedule service be started at computer where job deletion request is being sent to.

Security Requirements

Admin group membership is required to successfully execute NetScheduleJobDel on a remote server.

NET_API_STATUS
NetScheduleJobDel (

LPWSTR Servername,
DWORD MinJobId,
DWORD MaxJobId
);
Parameters

Servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

MinJobId

Minimum job identifier. Jobs with job identifier smaller than MinJobId will not be deleted.

MaxJobId

Maximum job identifier. Jobs with job identifier bigger than MaxJobId will not be deleted.

This function deletes all jobs whose job identifier is in the range MinJobId through MaxJobId. To delete all jobs at the server, one may call this function with MinJobId equal to 0 and MaxJobId equal to (DWORD) − 1. To delete just one particular job, one may choose MinJobId and MaxJobId both equal to that particular job's identifier.


NetScheduleJobEnum

NetScheduleJobEnum lists the jobs queued on a specified computer. NetScheduleJobEnum requires that the Schedule service be started.

Security Requirements

Admin group membership is required to successfully execute NetScheduleJobEnum on a remote server.

NET_API_STATUS
NetScheduleJobEnum(

LPWSTR Servername,
LPBYTE * PointerToBuffer,
DWORD PreferredMaximumLength,
LPDWORD EntriesRead,
LPDWORD TotalEntries,
LPDWORD ResumeHandle
);
Parameters

Servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

PointerToBuffer

On return a pointer to the return information structure is returned in the address pointed to by PointerToBuffer. The return information structure is an array of AT_ENUM data structures.

PreferredMaximumLength

Preferred maximum length of returned data (in 8-bit bytes).

EntriesRead

On return the actual enumerated element count is located in the DWORD pointed to by EntriesRead.

TotalEntries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by TotalEntries.

ResumeHandle

On return, a resume handle is stored in the DWORD pointed to by ResumeHandle, and is used to continue an job enumeration. The handle should be zero on the first call and left unchanged for subsequent calls. If ResumeHandle is NULL, then no resume handle is stored.

Note that each entry returned contains the JobId field of AT_ENUM structure. The value of this field may be used in calls that require job identifier argument, such as in a call to NetScheduleJobDel( ).


NetScheduleJobGetInfo

NetScheduleJobGetInfo retrieves information about a particular job queued on a specified computer. NetScheduleJobGetInfo requires that the Schedule service be started.

Security Requirements

Admin group membership is required to successfully execute NetScheduleJobGetInfo on a remote server.

NET_API_STATUS
NetScheduleJobGetInfo (

LPWSTR Servername,
DWORD JobId,
LPBYTE * PointerToBuffer
);
Parameters

Servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

JobId

A job identifier of a job in question.

PointerToBuffer

On return a pointer to the buffer containing AT_INFO data structure describing job in question.


NetServerDiskEnum

NetServerDiskEnum retrieves a list of disk drives on a server.

Security Requirements

Admin or server operator group membership is required to successfully execute NetServerDiskEnum on a remote computer. No special group membership is required for local calls.

NET_API_STATUS
NetServerDiskEnum (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resume_handle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. 0 is the only valid level.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Prefered maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resume_handle

On return, a resume handle is stored in the DWORD pointed to by resume_handle, and is used to continue an existing server disk search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.


NetServerEnum

NetServerEnum lists all servers of the specified type(s) that are visible in the specified domain(s). For example, an application can call NetServerEnum to list all domain controllers only or all SQL servers only.

Note  If you require information on the type, name, and comment for a specific server, use the WNetEnumResource function.

Security Requirements

No special group membership is required to successfully execute NetServerEnum.

NET_API_STATUS
NetServerEnum (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
DWORD servertype,
LPTSTR domain,
LPDWORD resume_handle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. 100 and 101 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the doubleword pointed to by entriesread.

totalentries

return the total number of entries that could have been enumerated from the current resume position is located in the doubleword pointed to by totalentries.

servertype

A doubleword mask that filters server entries to return from the enumeration. The defined mask bits are:

Symbolic constant	Value	Meaning
SV_TYPE_WORKSTATION	0x00000001	All LAN Manager workstation
SV_TYPE_SERVER	0x00000002	All LAN Manager server
SV_TYPE_SQLSERVER	0x00000004	Any server running with Microsoft SQL Server
SV_TYPE_DOMAIN_CTRL	0x00000008	Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL	0x00000010	Backup domain controller
SV_TYPE_TIMESOURCE	0x00000020	Server running the timesource service
SV_TYPE_AFP	0x00000040	Apple File Protocol servers
SV_TYPE_NOVELL	0x00000080	Novell servers
SV_TYPE_DOMAIN_MEMBER	0x00000100	Domain Member
SV_TYPE_PRINT	0x00000200	Server sharing print queue
SV_TYPE_DIALIN	0x00000400	Server running dialin service
SV_TYPE_XENIX_SERVER	0x00000800	Xenix server
SV_TYPE_NT	0x00001000	Windows NT server
SV_TYPE_WFW	0x00002000	Server running Windows for Workgroups
SV_TYPE_POTENTIAL_BROWSER	0x00010000	Server that can run the browser service
SV_TYPE_BACKUP_BROWSER	0x00020000	Server running a browser service as backup
SV_TYPE_MASTER_BROWSER	0x00040000	Server running the master browser service
SV_TYPE_DOMAIN_MASTER	0x00080000	Server running the domain master browser
SV_TYPE_DOMAIN_ENUM	0x80000000	Domain announcement
SV_TYPE_ALL	0xffffffff	All servers
domain

A pointer to a Unicode string containing the name of the domain for which a list of servers is to returned. The domain must be the primary domain, one of the other domains for the workstation or the logon domain.

resume_handle

On return, a resume handle is stored in the doubleword pointed to by resume_handle, and is used to continue an existing server search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.


NetServerGetInfo

NetServerGetInfo retrieves information about the specified server.

Security Requirements

Admin or accounts, comm, print, or server operator group membership is required to successfully execute NetServerGetInfo at level 102 or higher. No special group membership is required for level 100 or level 101 calls.

NET_API_STATUS
NetServerGetInfo (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. 100, 101, and 102 are valid for all platforms. 302, 402, 403, and 502 are valid for the appropriate platform.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.


NetServerSetInfo

NetServerSetInfo sets a server's operating parameters; it can set them individually or collectively. This information is stored such that it remains in effect after the system has been reinitialized.

Security Requirements

Admin or server operator group membership is required to successfully execute NetServerSetInfo.

NET_API_STATUS
NetServerSetInfo (

LPTSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information to set. 100, 101, and 102 are valid for all platforms. 302, 402, 403, and 502 are valid for the appropriate platform. In addition, 1001 − 1006, 1009 − 1011, 1016 − 1018, 1021, 1022, 1028, 1029, and 1037 − 1043 are valid based on the restrictions for downlevel systems described preceding.

buf

A pointer to a buffer containing the server information.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetServerTransportAdd

NetServerTransportAdd binds the server to the transport.

Security Requirements

Admin group membership is required to successfully execute NetServerTransportAdd.

NET_API_STATUS
NetServerTransportAdd (

LPTSTR servername,
DWORD level,
LPBYTE bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. Only 0 is valid.

bufptr

A pointer to a buffer containing the server transport information structure.


NetServerTransportDel

NetServerTransportDel unbinds the transport from the server.

Security Requirements

Admin group membership is required to successfully execute NetServerTransportDel.

NET_API_STATUS
NetServerTransportDel (

LPWSTR servername,
LPWSTR transportname
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

transportname

A pointer to a Unicode string containing the name of the transport from which to unbind.


NetServerTransportEnum

NetServerTransportEnum supplies information about transports that are managed by the server.

Security Requirements

No special group membership is required to successfully execute NetServerTransportEnum.

NET_API_STATUS
NetServerTransportEnum (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resumehandle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. Only 0 is valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resumehandle

On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing server transport search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, then no resume handle is stored.


NetServiceControl

NetServiceControl controls the operations of network services.

Security Requirements

Admin, Power User or Server Operator group membership is required to successfully execute NetServiceControl unless the value of the opcode parameter is SERVICE_CTRL_INTERROGATE. In that case, no special group membership is required.

NET_API_STATUS
NetServiceControl (

LPTSTR servername,
LPTSTR service,
DWORD opcode,
DWORD arg,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

service

A pointer to a Unicode string containing the name of the service to receive the control command.

opcode

Control code to send to service:

Value	Meaning
SERVICE_CTRL_INTERROGATE	Obtain the status of the service
SERVICE_CTRL_PAUSE	Pause the service
SERVICE_CTRL_CONTINUE	Continue the paused service
SERVICE_CTRL_UNINSTALL	Stop the service
arg

Service specific contol argument to send to service

bufptr

A pointer to the return information structure is returned in the address pointed to by bufptr.


NetServiceEnum

NetServiceEnum retrieves information about all started services, including paused services.

Security Requirements

No special group membership is required to successfully execute NetServiceEnum.

NET_API_STATUS
NetServiceEnum (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resume_handle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required, 0, 1, and 2 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Prefered maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resume_handle

On return, a resume handle is stored in the DWORD pointed to by resume_handle, and is used to continue an existing service search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.


NetServiceGetInfo

NetServiceGetInfo retrieves information about a particular started service.

Security Requirements

No special group membership is required to successfully execute NetServiceGetInfo.

NET_API_STATUS
NetServiceGetInfo (

LPTSTR servername,
LPTSTR service,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

service

A pointer to a Unicode string containing the name of the service.

level

Level of information required. 0, 1, and 2 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.


NetServiceInstall

NetServiceInstall starts a network service.

Security Requirements

Admin, Power User or Server Operator group membership is required to successfully execute NetServiceInstall.

NET_API_STATUS
NetServiceInstall (

LPTSTR servername,
LPTSTR service,
DWORD argc,
LPTSTR argv[ ],
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

service

A pointer to a Unicode string containing the name of the service to start.

bufptr

On return a pointer to a SERVICE_INFO_2 structure is returned in the address pointed to by bufptr.

cmdargs

A pointer to a set of command line arguments to pass to the starting service as command line arguments.


NetSessionDel

NetSessionDel ends a session between a server and a workstation.

Security Requirements

Admin or server operator group membership is required to successfully execute NetSessionDel.

NET_API_STATUS
NetSessionDel (

LPTSTR servername,
LPTSTR UncClientName,
LPTSTR username,
DWORD reserved
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

UncClientName

A pointer to a Unicode string containing the computer name of the client to disconnect. If UncClientName is NULL, then all the sessions of the user in username will be deleted on the server specified.

username

A pointer to a Unicode string containing the name of the user whose session is to be terminated. A NULL indicates that all users' sessions from the client name specified are to be terminated.

reserved

Reserved, must be zero.


NetSessionEnum

NetSessionEnum provides information about all current sessions.

Security Requirements

Admin or server operator group membership is required to successfully execute NetSessionEnum at level 1 or level 2. No special group membership is required for level 0 or level 10 calls.

NET_API_STATUS
NetSessionEnum (

LPTSTR servername,
LPTSTR UncClientName,
LPTSTR username,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resume_handle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

UncClientName

A pointer to a Unicode string containing the name of the computer session for which information is to be returned. A NULL pointer or string specifies that all computer sessions on the server are to be enumerated.

username

A pointer to a Unicode string containing the name of the the user for which to enumerate the sessions. A NULL pointer or string specifies that sessions for all users are to be enumerated.

level

Level of information required. 0, 1, 2, and 10 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Prefered maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resume_handle

On return, a resume handle is stored in the DWORD pointed to by resume_handle, and is used to continue an existing session search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.


NetSessionGetInfo

NetSessionGetInfo retrieves information about a session established between a particular server and workstation.

Security Requirements

Admin or server operator group membership is required to successfully execute NetSessionGetInfo at level 1 or level 2. No special group membership is required for level 0 or level 10 calls.

NET_API_STATUS
NetSessionGetInfo (

LPTSTR servername,
LPTSTR UncClientName,
LPTSTR username,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

UncClientName

A pointer to a Unicode string containing the name of the computer session for which information is to be returned. This field cannot be NULL.

username

A pointer to a Unicode string containing the name of the user whose session information is to be returned. This field cannot be NULL.

level

Level of information required. 0, 1, 2, and 10 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.


NetShareAdd

NetShareAdd shares a server resource.

Security Requirements

Admin or comm, print, or server operator group membership is required to successfully execute NetShareAdd. The print operator can add only printer queues. The comm operator can add only communication-device queues.

NET_API_STATUS
NetShareAdd (

LPTSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information provided. Must be 2 or 502.

buf

A pointer to a buffer containing the share information structure.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetShareCheck

NetShareCheck checks whether or not a server is sharing a device.

Security Requirements

No special group membership is required to successfully execute NetShareCheck.

NET_API_STATUS
NetShareCheck (

LPTSTR servername,
LPTSTR device,
LPDWORD type
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

device

A pointer to a Unicode string containing the name of the device to check for shared access.

type

On return the address pointed to by the type parameter contains the type of share the device is offered with. This field is set only if success was returned.


NetShareDel

NetShareDel deletes a share name from a server's list of shared resources, disconnecting all connections to the shared resource.

Security Requirements

Admin or comm, print, or server operator group membership is required to successfully execute NetShareDel. The print operator can delete only printer queues. The comm operator can delete only communication-device queues.

NET_API_STATUS
NetShareDel (

LPTSTR servername,
LPTSTR netname,
DWORD reserved
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

netname

A pointer to a Unicode string containing the netname of the share to delete.

reserved

Reserved, must be zero.


NetShareEnum

NetShareEnum retrieves information about each shared resource on a server. The NetShareEnum function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetEnumResource function.

Security Requirements

Admin or comm, print, or server operator group membership is required to successfully execute NetShareEnum at level 2. No special group membership is required for level 0 or level 1 calls.

NET_API_STATUS
NetShareEnum (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resume_handle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. 0, 1, 2, and 502 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Prefered maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resume_handle

On return, a resume handle is stored in the DWORD pointed to by resume_handle, and is used to continue an existing share search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.


NetShareGetInfo

NetShareGetInfo retrieves information about a particular shared resource on a server.

Security Requirements

Admin or comm, print, or server operator group membership is required to successfully execute NetShareGetInfo at level 2. No special group membership is required for level 0 or level 1 calls.

NET_API_STATUS
NetShareGetInfo (

LPTSTR servername,
LPTSTR netname,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

netname

A pointer to a Unicode string containing the netname of the share to return information on.

level

Level of information required. 0, 1, 2, and 502 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.


NetShareSetInfo

NetShareSetInfo sets the parameters of a shared resource.

Security Requirements

Admin or comm, print, or server operator group membership is required to successfully execute NetShareSetInfo. The print operator can set information only about printer queues. The comm operator can set information only about communication-device queues.

NET_API_STATUS
NetShareSetInfo (

LPTSTR servername,
LPTSTR netname,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

netname

A pointer to a Unicode string containing the netname of the share to set information on.

level

Level of information to set. 1, 2, 502, 1004 − 1006, and 1501 are valid.

buf

A pointer to a buffer containing the share information.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetStatisticsGet

NetStatisticsGet retrieves operating statistics for a service. Currently, only the Workstation and Server services are supported.

Security Requirements

Admin or server operator group membership is required to successfully execute NetStatisticsGet on a remote server.

NET_API_STATUS
NetStatisticsGet (

LPTSTR server,
LPTSTR service,
DWORD level,
DWORD options,
LPBYTE * bufptr
);
Parameters

server

Points to a Unicode string that contains the name of the server on which to execute NetConfigGet. A NULL pointer or NULL string specifies the local computer.

service

Points to a Unicode string that contains the name of the service about which to get the statistics. Only the values SERVER and WORKSTATION are currently allowed.

level

Specifies the level of detail requested; must be 0.

options

Must be 0.

bufptr

On return a pointer to the returned information is returned in the address pointed to by bufptr.


NetUseAdd

NetUseAdd establishes a connection between a local or NULL device name and a shared resource by redirecting the local or NULL (UNC) device name to the shared resource. The NetUseAdd function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetAddConnection2 function.

Security Requirements

No special group membership is required for this call. This function cannot be executed on a remote server.

NET_API_STATUS
NetUseAdd (

LPTSTR UncServerName,
DWORD Level,
LPBYTE Buf,
LPDWORD ParmError
);
Parameters

UncServerName

Must be NULL.

Level

Level of information to set. 1 and 2 are valid.

Buf

A pointer to a buffer containing the use information structure.

ParmError

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetUseDel

NetUseDel ends a connection to a shared resource. The NetUseDel function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetCancelConnection2 function.

Security Requirements

No special group membership is required for this call. This function cannot be executed on a remote server.

NET_API_STATUS
NetUseDel (

LPTSTR UncServerName,
LPTSTR UseName,
DWORD ForceCond
);
Parameters

UncServerName

Must be NULL.

UseName

A pointer to a Unicode string containing the path of the use to delete.

ForceCond

Level of force to use in deleting the use.


NetUseEnum

NetUseEnum lists all current connections between the local computer and resources on remote servers. The NetUseEnum function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetEnumResource function.

Security Requirements

No special group membership is required for this call. This function cannot be executed on a remote server.

NET_API_STATUS
NetUseEnum (

LPTSTR UncServerName,
DWORD Level,
LPBYTE * BufPtr,
DWORD PreferredMaximumSize,
LPDWORD EntriesRead,
LPDWORD TotalEntries,
LPDWORD ResumeHandle
);
Parameters

UncServerName

Must be NULL.

Level

Level of information provided. Must be 0, 1, or 2.

BufPtr

On return a pointer to the return information structure is returned in the address pointed to by BufPtr.

PreferredMaximumSize

Prefered maximum length of returned data (in 8-bit bytes).

EntriesRead

On return the actual enumerated element count is located in the DWORD pointed to by EntriesRead.

TotalEntries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by TotalEntries.

ResumeHandle

On return, a resume handle is stored in the DWORD pointed to by ResumeHandle, and is used to continue an existing use search. The handle should be zero on the first call and left unchanged for subsequent calls. If ResumeHandle is NULL, then no resume handle is stored.


NetUseGetInfo

NetUseGetInfo retrieves information about a connection to a shared resource. The NetUseGetInfo function is obsolete. It is provided only for compatibility with LAN Manager and 16-bit versions of Windows. Win32-based applications should use the WNetGetConnection function.

Security Requirements

No special group membership is required for this call. This function cannot be executed on a remote server.

NET_API_STATUS
NetUseGetInfo (

LPTSTR UncServerName,
LPTSTR UseName,
DWORD Level,
LPBYTE * BufPtr
);
Parameters

UncServerName

Must be NULL.

UseName

A pointer to a Unicode string containing the local or remote name active use to return information on.

Level

Level of information required. 0, 1, and 2 are valid.

BufPtr

On return a pointer to the return information structure is returned in the address pointed to by BufPtr.


NetUserAdd

NetUserAdd adds a user account.

Security Requirements

Admin or account operator group membership is required to successfully execute NetUserAdd.

NET_API_STATUS
NetUserAdd (

LPWSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information provided. Must be 1, 2, or 3.

buf

A pointer to a buffer containing the user information structure.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetUserChangePassword  (preliminaryWindows NT)
NetUserChangePassword  (preliminary−Windows NT)

The NetUserChangePassword function changes a user's password for a specified network server or domain.

Security Requirements

A server or domain can be configured to require that a user log on to change the password on a user account. If that is the case, you need administrator or account operator access to change the password for another user acount. If logging on is not required, you can change the password for any user account, so long as you know the current password.

NET_API_STATUS NetUserChangePassword(

LPWSTR  domainname,	// pointer to server or domain name string
LPWSTR  username,	// pointer to user name string
LPWSTR  oldpassword,	// pointer to old password string
LPWSTR  newpassword,	// pointer to new password string
);
Parameters

domainname

Pointer to a null-terminated Unicode string that specifies the name of a remote server or domain. The NetUserChangePassword function changes the user's password on that remote server or domain.

A domainname value of NULL specifies the logon domain of the caller.

username

Pointer to a null-terminated Unicode string that specifies a user name. The NetUserChangePassword function changes the password for that user.

A username value of NULL specifies the logon user name of the caller.

oldpassword

Pointer to a null-terminated Unicode string that specifies the user's old password on the server or domain.

newpassword

Pointer to a null-terminated Unicode string that specifies the user's new password on the server or domain.

Return Value

The function returns a NET_API_STATUS value.


NetUserDel

NetUserDel deletes a user account from the accounts database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetUserDel.

NET_API_STATUS
NetUserDel (

LPWSTR servername,
LPWSTR username
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

username

A pointer to a Unicode string containing the name of the user account to delete.


NetUserEnum

NetUserEnum provides resumable enumeration of information about each user account in a domain.

Security Requirements

Admin or account operator group membership is required to successfully execute NetUserEnum at levels 1 and 2. No special group membership is required at level 0 or 10.

NET_API_STATUS
NetUserEnum (

LPWSTR servername,
DWORD level,
DWORD filter,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resumehandle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. 0, 1, 2, 3, 10, 11, and 20 are valid.

filter

Specifies a filter of account types ot enumerate. 0 implies all account types. Allowable values are:

FILTER_TEMP_DUPLICATE_ACCOUNTS

FILTER_NORMAL_ACCOUNT

FILTER_INTERDOMAIN_TRUST_ACCOUNT

FILTER_WORKSTATION_TRUST_ACCOUNT

FILTER_SERVER_TRUST_ACCOUNT

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries. EXCEPTION: If the call is to a computer that is running OS/2 LANMAN, the totalentries will always reflect the total number of entries in the database no matter where it is in the resume sequence.

resumehandle

On return, a resume handle is stored in the DWORD pointed to by resumehandle and is used to continue an existing user search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, then no resume handle is stored.


NetUserGetGroups

NetUserGetGroups retrieves a list of global groups to which a specified user belongs.

Security Requirements

Admin or account operator group membership is required to successfully execute NetUserGetGroups.

NET_API_STATUS
NetUserGetGroups (

LPWSTR servername,
LPWSTR username,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

username

A pointer to a Unicode string containing the name of the user to return global group membership for.

level

Level of information required. Only 0 or 1 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr. The returned information is an array of GROUP_USERS_INFO_x structures.

prefmaxlen

Prefered maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the b pointed to by totalentries.


NetUserGetInfo

NetUserGetInfo retrieves information about a particular user account on a server.

Security Requirements

No special group membership is required to successfully execute NetUserGetInfo. This is a change from LAN Manager, which required administer or account operator privilege to call this function at information levels above 0 (except for the user's own account, which could use level 11).

NET_API_STATUS
NetUserGetInfo (

LPWSTR servername,
LPWSTR username,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

username

A pointer to a Unicode string containing the name of the user account on which to return information.

level

Level of information required. 0, 1, 2, 3,10,11, and 20 are valid.

bufptr

A pointer to the return information structure is returned in the address pointed to by bufptr.


NetUserGetLocalGroups

NetUserGetLocalGroups retrieves a list of local groups to which a specified user belongs.

Security Requirements

Admin or account operator group membership is required to successfully execute NetUserGetLocalGroups.

NET_API_STATUS
NetUserGetLocalGroups (

LPWSTR servername,
LPWSTR username,
DWORD level,
DWORD flags,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

username

A pointer to a Unicode string containing the name of the user to return global group membership for.

level

Level of information required. Only 0 is valid.

flags

Bitmask of flags. Currently, only LG_INCLUDE_INDIRECT is defined. If this bit is set, the function will also return localgroups the user is a member of indirectly (i.e., by the virtue of being in a globalgroup that itself is a member of one or more localgroups).

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr. The returned information is an array of LOCALGROUP_USERS_INFO_0 structures.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.


NetUserModalsGet

NetUserModalsGet retrieves global information for all users and global groups in the user account database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetUserModalsGet.

NET_API_STATUS
NetUserModalsGet (

LPWSTR servername,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. 0, 1, and 2 are valid.

bufptr

A pointer to the return information structure is returned in the address pointed to by bufptr.


NetUserModalsSet

NetUserModalsSet sets global information for all users and global groups in the user account database.

Security Requirements

Admin or account operator group membership is required to successfully execute NetUserModalsSet.

NET_API_STATUS
NetUserModalsSet (

LPWSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

username

A pointer to a Unicode string containing the name of the user account to set information on.

level

Level of information to set. 0, 1, and 2 are valid.

buf

A pointer to a buffer containing the user modals information.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetUserSetGroups

NetUserSetGroups sets global group memberships for a specified user account.

Security Requirements

Admin or account operator group membership is required to successfully execute NetUserSetGroups.

NET_API_STATUS
NetUserSetGroups (

LPWSTR servername,
LPWSTR username,
DWORD level,
LPBYTE buf,
DWORD num_entries
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

username

A pointer to a Unicode string containing the name of the user to set global group memberships for.

level

Level of information required. Only 0 or 1 are valid.

buf

A pointer to an array of global groups information structures.

num_entries

Number of global group information structures contained in the array pointed to by buf.


NetUserSetInfo

NetUserSetInfo sets the parameters of a user account.

Security Requirements

Admin or account operator group membership is required to successfully execute NetUserSetInfo. A user may call NetUserSetInfo to set certain information on his/her own account.

NET_API_STATUS
NetUserSetInfo (

LPWSTR servername,
LPWSTR username,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

username

A pointer to a Unicode string containing the name of the user account to set information on.

level

Level of information to set. 0, 1, 2, 3, or 20.

buf

A pointer to a buffer containing the user information.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetWkstaGetInfo

NetWkstaGetInfo returns information about the configuration elements for a workstation.

Security Requirements

Security requirements are described with the data structures for the information levels above.

NET_API_STATUS
NetWkstaGetInfo (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. 100, 101, 102, 302, 402, and 502 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.


NetWkstaSetInfo

NetWkstaSetInfo configures a workstation. This information is stored such that it remains in effect after the system has been reinitialized.

Security Requirements

Admin group membership is required to successfully execute NetWkstaSetInfo.

NET_API_STATUS
NetWkstaSetInfo (

LPTSTR servername,
DWORD level,
LPBYTE buf,
LPDWORD parm_err
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information to set. 100, 101, 102, 302, 402, and 502 are valid. In addition, 1010 − 1013, 1018, 1023, 1027, 1028, 1032, 1033, 1035, and 1041-1062 are valid based on the restrictions mentioned preceding.

buf

A pointer to a buffer containing the workstation information.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NetWkstaTransportAdd

NetWkstaTransportAdd binds the redirector to the transport.

Security Requirements

Admin group membership is required to successfully execute NetWkstaTransportAdd.

NET_API_STATUS
NetWkstaTransportAdd (

LPTSTR servername,
DWORD level,
LPBYTE buf
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. Only 0 is valid.

buf

A pointer to a buffer containing the server transport information structure.


NetWkstaTransportDel

NetWkstaTransportDel unbinds the transport from the redirector.

Security Requirements

Admin group membership is required to successfully execute NetWkstaTransportDel.

NET_API_STATUS
NetWkstaTransportDel (

LPTSTR servername,
LPTSTR transportname,
DWORD ucond
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

transportname

A pointer to a Unicode string containing the name of the transport from which to unbind.

ucond

Force level to delete connections on the transport binding.


NetWkstaTransportEnum

NetWkstaTransportEnum supplies information about transports that are managed by the redirector.

Security Requirements

No special group membership is required to successfully execute NetWkstaTransportEnum.

NET_API_STATUS
NetWkstaTransportEnum (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resumehandle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information required. Only 0 is valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Preferred maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resumehandle

On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing workstation transport search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, then no resume handle is stored.


NetWkstaUserEnum

NetWkstaUserEnum lists information about all current users on the workstation.

Security Requirements

Admin group membership is required to successfully execute NetWkstaUserEnum both locally and on a remote server.

NET_API_STATUS
NetWkstaUserEnum (

LPTSTR servername,
DWORD level,
LPBYTE * bufptr,
DWORD prefmaxlen,
LPDWORD entriesread,
LPDWORD totalentries,
LPDWORD resumehandle
);
Parameters

servername

A pointer to a Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local computer.

level

Level of information provided. Must be 0 or 1.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.

prefmaxlen

Prefered maximum length of returned data (in 8-bit bytes).

entriesread

On return the actual enumerated element count is located in the DWORD pointed to by entriesread.

totalentries

On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.

resumehandle

On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing use search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, then no resume handle is stored.


NetWkstaUserGetInfo

NetWkstaUserGetInfo returns the user-specific information about the configuration elements for a workstation.

Security Requirements

Security requirements are described with the data structures for the information levels above. This function only works locally.

NET_API_STATUS
NetWkstaUserGetInfo (

LPTSTR reserved,
DWORD level,
LPBYTE * bufptr
);
Parameters

reserved

This field must be set to NULL.

level

Level of information required. 0 and 1 are valid.

bufptr

On return a pointer to the return information structure is returned in the address pointed to by bufptr.


NetWkstaUserSetInfo

NetWkstaUserSetInfo sets the user-specific information about the configuration elements for a workstation.

Security Requirements

Security requirements are described with the data structures for the information levels above. This function only works locally.

NET_API_STATUS
NetWkstaUserSetInfo (

LPTSTR reserved,
DWORD level,
LPBYTE * buf,
LPDWORD parm_err
);
Parameters

reserved

This field must be set to zero.

level

Level of information required. 0 and 1 are valid.

buf

On return a pointer to the return information structure is returned in the address pointed to by buf.

parm_err

Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.


NotifyBootConfigStatus

The NotifyBootConfigStatus function notifies the service control manager as to the acceptability of the configuration that booted the system.

An acceptable configuration triggers the storage of that configuration as the last-known good configuration; an unacceptable configuration triggers a system reboot.

BOOL NotifyBootConfigStatus(

BOOL  BootAcceptable	// indicates acceptability of boot configuration
);
Parameters

BootAcceptable

Specifies whether the configuration that booted the system is acceptable. If this parameter's value is TRUE, the service control manager saves the configuration that booted the system as the last-known good configuration. If the parameter's value is FALSE, the system immediately reboots, using the previously saved last-known good configuration.

Return Value

If the BootAcceptable parameter 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. To get extended error information, call GetLastError.

Errors

The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager to deal with the configuration registry.

Value	Meaning
ERROR_ACCESS_DENIED	The caller does not have permission to perform this operation.  A hard-coded DACL associated with the service control manager object determines who can perform a NotifyBootConfigStatus operation. Only the operating system and members of the local adminstrators group can do so.
Remarks

The NotifyBootConfigStatus function is used to save the configuration from which  a running system was booted. 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.


NotifyChangeEventLog

The NotifyChangeEventLog function lets an application receive notification when an event is written to the event log file specified by hEventLog. When the event is written to the event log file, the function causes the event object specified by hEvent to become signaled.

BOOL NotifyChangeEventLog(

HANDLE  hEventLog,	// special default locale value to be converted
HANDLE  hEvent	// special default locale value to be converted
);
Parameters

hEventLog

Handle to an event log file, obtained by calling OpenEventLog. When an event is written to this log file, the event specified by hEvent becomes signaled.

hEvent

A handle to a Win32 event. This is the event that becomes signaled when an event is written to the event log file specified by hEventLog.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The NotifyChangeEventLog function does not work with remote handles. If hEventLog is the handle of an event log on a remote computer, the NotifiyChangeEventLog function returns FALSE, and GetLastError  returns ERROR_INVALID_HANDLE.

See Also

OpenEventLog


ntohl

The Windows Sockets ntohl function converts a u_long from network byte order to host byte order.

u_long ntohl (

u_long netlong
);
Parameters

netlong

A 32-bit number in network byte order.

Return Value

ntohl returns the value in host byte order.

Remarks

This function takes a 32-bit number in network byte order and returns a 32-bit number in host byte order.

See Also

htonl, htons, ntohs


ntohs

The Windows Sockets ntohs function converts a u_short from network byte order to host byte order.

u_short ntohs (

u_short netshort
);
Parameters

netshort

A 16-bit number in network byte order.

Return Value

ntohs returns the value in host byte order.

Remarks

This function takes a 16-bit number in network byte order and returns a 16-bit number in host byte order.

See Also

htonl, htons, ntohl


ObjectCloseAuditAlarm

The ObjectCloseAuditAlarm function generates audit messages when a handle of an object is deleted. Alarms are not supported in the current version of Windows NT.

BOOL ObjectCloseAuditAlarm(

LPCTSTR  SubsystemName,	// address of string for subsystem name
LPVOID  HandleId,	// address of handle identifier
BOOL  GenerateOnClose	// flag for audit generation
);
Parameters

SubsystemName

Points to a null-terminated string specifying the name of the subsystem calling the function, for example, "DEBUG" or "WIN32".

HandleId

Specifies a unique 32-bit value representing the client's handle of the object. This should be the same value that was passed to the AccessCheckAndAuditAlarm or ObjectOpenAuditAlarm function.

GenerateOnClose

Specifies a flag set by a call to the AccessCheckAndAuditAlarm or ObjectOpenAuditAlarm function when the object handle is created.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The 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

The ObjectOpenAuditAlarm function generates audit messages when a client application attempts to gain access to an object or to create a new one. Alarms are not supported in the current version of Windows NT.

BOOL ObjectOpenAuditAlarm(

LPCTSTR  SubsystemName,	// address of string for subsystem name
LPVOID  HandleId,	// address of handle identifier
LPTSTR  ObjectTypeName,	// address of string for object type
LPTSTR  ObjectName,	// address of string for object name
PSECURITY_DESCRIPTOR  pSecurityDescriptor,	// address of security descriptor
HANDLE  ClientToken,	// handle of client's access token
DWORD  DesiredAccess,	// mask for desired access rights
DWORD  GrantedAccess,	// mask for granted access rights
PPRIVILEGE_SET  Privileges,	// address of privileges
BOOL  ObjectCreation,	// flag for object creation
BOOL  AccessGranted,	// flag for results
LPBOOL  GenerateOnClose	// address of flag for audit generation
);
Parameters

SubsystemName

Points to a null-terminated string specifying the subsystem calling this function, for example, "DEBUG" or "WIN32".

HandleId

Points to a unique 32-bit value representing the client's handle of the object. If the access is denied, this parameter is ignored.

ObjectTypeName

Points to a null-terminated string specifying the type of object to which the client is requesting access. This string appears in the audit log for the object.

ObjectName

Points to a null-terminated string specifying the name of the object to which the client gained access or attempted to gain access. This string appears in the audit log for the object.

pSecurityDescriptor

Points to the SECURITY_DESCRIPTOR structure for the object being accessed.

ClientToken

Identifies an access token representing the client requesting the operation. This handle must be obtained by opening the token of a thread impersonating the client. The token must be open for TOKEN_QUERY access.

DesiredAccess

Specifies the desired access mask. This mask must have been previously mapped by the MapGenericMask function to contain no generic access rights.

GrantedAccess

Specifies an access mask indicating which access rights are granted. This access mask is intended to be the same value set by one of the access-checking functions in its GrantedAccess parameter. Examples of access-checking functions include AccessCheckAndAuditAlarm and AccessCheck.

Privileges

Points to a PRIVILEGE_SET structure that specifies the set of privileges required for the access attempt. This parameter can be NULL.

ObjectCreation

Specifies a flag that determines whether the application creates a new object when access is granted. When this flag is TRUE, the application creates a new object; when it is FALSE, the application opens an existing object.

AccessGranted

Specifies a flag indicating whether access was granted or denied in a previous call to an access-checking function, such as AccessCheck. If access was granted, this flag is TRUE. If not, it is FALSE.

GenerateOnClose

Points to a flag set by the audit-generation routine when the function returns. This flag must be passed to the ObjectCloseAuditAlarm function when the object handle is closed.

Return Value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The 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,


IContextMenu

Designates an interface that enables the shell to retrieve extensions to context menus.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IContextMenu Methods	Description
QueryContextMenu	Adds commands to a context menu.
InvokeCommand	Carries out a menu command, either in response to user input or otherwise.
GetCommandString	Retrieves the language-independent name of a menu command or the help text for a menu command.


IContextMenu::GetCommandString

Retrieves the language-independent command string or the help text for a context menu item.

HRESULT STDMETHODCALLTYPE GetCommandString(

LPCONTEXTMENU pIface,
UINT idCmd,
UINT uFlags,
UINT *pwReserved,
LPSTR pszName,
UINT cchMax
);
Parameters

pIface

Pointer to the IContextMenu interface. In C++, this parameter is implicit.

idCmd

Menu item identifier offset.

uFlags

Flag specifying the information to retrieve. This parameter can be one of the following values:

GCS_HELPTEXT	Returns the help text for the menu item.
GCS_VALIDATE	Validates that the menu item exists.
GCS_VERB	Returns the language-independent command name for the menu item.
pwReserved

Reserved. Applications must specify NULL when calling this method, and handles must ignore this parameter when called.

pszName and cchMax

Address and size of the buffer that receives the null-terminated string.

Return Value

Returns NOERROR if successful or an OLE-defined error code otherwise.

The language-independent command name is a name that can be passed to the IContextMenu::InvokeCommand method to activates a command by an application. The help text is a description that the Explorer displays in its status bar; it should be reasonably short (under 40 characters).

See Also

IContextMenu


IContextMenu::InvokeCommand

Carries out the command associated with a context menu item.

HRESULT STDMETHODCALLTYPE InvokeCommand(

LPCONTEXTMENU pIface,
LPCMINVOKECOMMANDINFO lpici
);
Parameters

pIface

Pointer to the IContextMenu interface. In C++, this parameter is implicit.

lpici

Pointer to a CMINVOKECOMMANDINFO structure containing information about the command.

Return Value

Returns NOERROR if successful or an OLE-defined error code otherwise.

The shell calls this method when the user chooses a command that the handler added to a context menu. This method may also be called by an application without any corresponding user action.

See Also

CMINVOKECOMMANDINFO, IContextMenu


IContextMenu::QueryContextMenu

Adds menu items to the specified menu. The menu items should be inserted at a given position in the menu, and their menu item identifiers must be in a given range.

HRESULT STDMETHODCALLTYPE QueryContextMenu(

LPCONTEXTMENU pIface,
HMENU hmenu,
UINT indexMenu,
UINT idCmdFirst,
UINT idCmdLast,
UINT uFlags
);
Parameters

pIface

Pointer to the IContextMenu interface. In C++, this parameter is implicit.

hmenu

Handle of the menu. The handler should specify this handle when calling the InsertMenu or InsertMenuItem function.

indexMenu

Zero-based position at which to insert the first menu item.

idCmdFirst and idCmdLast

Minimum and maximum values that the handler can specify for menu item identifiers. The actual identifier of each menu item should be idCmdFirst plus a menu identifier offset in the range zero through (idCmdLast − idCmdFirst).

uFlags

Flag specifying zero or more of the following values:

CMF_DEFAULTONLY	The user is activating the default action, typically by double-clicking. A context menu extension or drag and drop handler should not add any menu items if this value is specified. A name space extension should add only the default item (if any).
CMF_EXPLORER	Context menu handlers should ignore this value. This value is specified if the context menu is for an object in the left pane of the explorer.
CMF_NORMAL	Indicates normal operation. A context menu extension, name space extension, or drag and drop handler can add any menu items.
CMF_VERBSONLY	Context menu handlers should ignore this value. This value is specified if the context menu is for a shortcut object.
The remaining bits of the low-order word are reserved by the system. The high-order word may be used for context-specific communications.

Return Value

Returns an HRESULT structure in which, if the method is successful, the code member contains the menu identifier offset of the last menu item added.

See Also

IContextMenu, InsertMenu, InsertMenuItem


ICopyHook

Designates an interface that allows a copy hook handler to prevent a folder or printer object from being copied, moved, deleted, or renamed. The shell calls a copy hook handler whenever file system directories are about to be copied, moved, deleted, or renamed, as well as whenever the status of a printer is about to change.

The shell initializes the copy hook handler interface directly — that is, without using the IShellExtInit interface first. A folder object can have multiple copy hook handlers. A copy hook handler interface has one method, CopyCallBack.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IContextMenu Methods	Description
CopyCallBack	Carries out a move, copy, delete, or rename operation on a folder object, or prevents the shell from carrying out the operation.


ICopyHook::CopyCallback

Either allows the shell to carry out a move, copy, delete, or rename operation on a folder object, or prevents the shell from carrying out the operation. The shell calls each copy hook handler registered for a folder object until either all the handlers have been called or any handler returns IDCANCEL.

HRESULT STDMETHODCALLTYPE CopyCallback(

ICopyHook FAR * pCopyHook,
HWND hwnd,
UINT wFunc,
UINT wFlags,
LPCSTR pszSrcFile,
DWORD dwSrcAttribs,
LPCSTR pszDestFile,
DWORD dwDestAttribs
);
Parameters

pCopyHook

Pointer to the ICopyHook interface. In C++, this parameter is implicit.

hwnd

Handle of the window that the copy hook handler should use as the parent window for any user interface elements the handler may need to display. If FOF_SILENT is specified, the method should ignore this parameter.

wFunc

Operation to perform. This parameter can be one of the following values:

FO_COPY	Copies the file specified by pszSrcFile to the location specified by pszDestFile.
FO_DELETE	Deletes the file specified by pszSrcFile.
FO_MOVE	Moves the file specified by pszSrcFile to the location specified by pszDestFile.
FO_RENAME	Renames the file specified by pszSrcFile.
PO_DELETE	Deletes the printer specified by pszSrcFile.
PO_PORTCHANGE	Changes the printer port. The pszSrcFile and pszDestFile parameters contain double null-terminated lists of strings. Each list contains the printer name followed by the port name. The port name in pszSrcFile is the current printer port, and the port name in pszDestFile is the new printer port.
PO_RENAME	Renames the printer specified by pszSrcFile.
PO_REN_PORT	Combination of PO_RENAME and PO_PORTCHANGE.
wFlags

Flags that control the operation. This parameter can be a combination of the following values:

FOF_ALLOWUNDO	Preserves undo information (if possible).
FOF_CONFIRMMOUSE	Not implemented.
FOF_FILESONLY	Not implemented. The shell calls a copy hook handler only for folder objects, not files.
FOF_MULTIDESTFILES	The SHFileOperation function specified multiple destination files (one for each source file) rather than one directory where all the source files are to be deposited. A copy hook handler typically ignores this value.
FOF_NOCONFIRMATION	Responds with "yes to all" for any dialog box that is displayed.
FOF_NOCONFIRMMKDIR	Does not confirm the creation of any needed directories if the operation requires a new directory to be created.
FOF_RENAMEONCOLLISION	Gives the file being operated on a new name (such as, "Copy #1 of ...") in a copy, move, or rename operation if a file of the target name already exists.
FOF_SILENT	Displays no progress dialog box.
FOF_SIMPLEPROGRESS	Displays a progress dialog box, but the dialog box does not show the names of the files.
pszSrcFile

Pointer to a string that contains the name of the source file.

dwSrcAttribs

Attributes of the source file. This parameter can be a combination of any of the file attribute flags (FILE_ATTRIBUTE_*) defined in the Windows header files.

pszDestFile

Pointer to a string that contains the name of the destination file.

dwDestAttribs

Attributes of the source file. This parameter can be a combination of any of the file attribute flags (FILE_ATTRIBUTE_*) defined in the Windows header files.

Return Value

Returns an integer value that indicates whether the shell should perform the operation. It can be one of the following values:

IDYES	Allows the operation.
IDNO	Prevents the operation on this file, but continues with any other operations (for example, a batch copy operation).
IDCANCEL	Prevents the current operation and cancels any pending operations.
See Also

ICopyHook


IExtractIcon

Designates an interface that enables the shell to retrieve icons for file objects or folders.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IExtractIcon Methods	Description
GetIconLocation	Retrieves the icon location for a file object.
ExtractIcon	Extracts an icon from the specified location.


IExtractIcon::ExtractIcon

Extracts an icon image from the specified location.

HRESULT STDMETHODCALLTYPE ExtractIcon(

LPEXTRACTICON pIface,
LPCSTR pszFile,
UINT nIconIndex,
HICON *phiconLarge,
HICON *phiconSmall,
UINT nIconSize
);
Parameters

pIface

Pointer to the IExtractIcon interface. In C++, this parameter is implicit.

pszFile

Pointer to a null-terminated string specifying the icon location.

nIconIndex

Icon index.

phiconLarge and phiconSmall

Addresses of variables that receive the handles of the large and small icons, respectively.

nIconSize

Value specifying the size, in pixels, of the large icon required. The size specified can be the width or height. The width of an icon always equals its height.

Return Value

Returns NOERROR if the function extracted the icon or S_FALSE if the calling application should extract the icon.

The icon location and index are the same values returned by the IExtractIcon::GetIconLocation method. If this function returns S_FALSE, these values must specify an icon filename and index. If this function does not return S_FALSE, the calling application should make no assumptions about the meanings of the pszFile and nIconIndex parameters.

See Also

IExtractIcon, IExtractIcon::GetIconLocation


IExtractIcon::GetIconLocation

Retrieves the location and index of an icon.

HRESULT STDMETHODCALLTYPE GetIconLocation(

LPEXTRACTICON pIface,
UINT uFlags,
LPSTR szIconFile,
INT cchMax,
int *piIndex,
UINT *pwFlags
);
Parameters

pIface

Pointer to the IExtractIcon interface. In C++, this parameter is implicit.

uFlags

Flags. This parameter can be zero or the following values:

GIL_FORSHELL	The icon is to be displayed in a shell folder.
GIL_OPENICON	The icon is for a folder that is open.
szIconFile and cchMax

Address and size of the buffer that receives the icon location. The icon location is a null-terminated string that typically specifies the name of an icon file.

piIndex

Pointer to an integer that receives the icon index.

pwFlags

Pointer to an unsigned integer that receives zero or more of the following values:

GIL_DONTCACHE	The icon should not be cached.
GIL_NOTFILENAME	The location is not a filename. To extract the icon from the location, use the IExtractIcon::ExtractIcon method.
GIL_PERCLASS	All file objects of this class have the same icon.
GIL_PERINSTANCE	Each file object of this class has its own icon.
GIL_SIMULATEDOC	The shell should create a document icon using the specified icon.
Return Value

Returns NOERROR if the function returned a valid location or S_FALSE if the shell should use a default icon.

See Also

IExtractIcon, IExtractIcon::ExtractIcon


IShellPropSheetExt

Designates an interface that allows a property sheet handler to add or replace pages in the property sheet for a file object.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
i

IShellPropSheetExt Methods	Description
AddPages	Adds one or more pages to a property sheet for a file object.
ReplacePage	Replaces a page in a property sheet for a control panel object.


IShellPropSheetExt::AddPages

Adds one or more pages to a property sheet that the shell displays for a file object. When it is about to display the property sheet, the shell calls the AddPages method of each property sheet handler registered to the file type.

HRESULT STDMETHODCALLTYPE AddPages(

IShellPropSheetExt FAR * pProp,
LPFNADDPROPSHEETPAGE lpfnAddPage,
LPARAM lParam
);
Parameters

pProp

Pointer to the IShellPropSheetExt interface. In C++, this parameter is implicit.

lpfnAddPage

Pointer to a function that the property sheet handler calls to add a page to the property sheet. The function takes a property sheet handle returned by the CreatePropertySheetPage function and the lParam parameter passed to the AddPages method.

lParam

Parameter to pass to the function specified by lpfnAddPage.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

For each page it needs to add to a property sheet, a property sheet handler fills a PROPSHEETPAGE structure, calls CreatePropertySheetPage, and then calls the function specified by lpfnAddPage.

See Also

CreatePropertySheetPage, IShellPropSheetExt, PROPSHEETPAGE


IShellPropSheetExt::ReplacePage

Replaces a page in a property sheet for a control panel object.

HRESULT STDMETHODCALLTYPE ReplacePage(

IShellPropSheetExt FAR * pProp,
UINT uPageID,
LPFNADDPROPSHEETPAGE lpfnReplacePage,
LPARAM lParam
);
Parameters

pProp

Pointer to the IShellPropSheetExt interface. In C++, this parameter is implicit.

uPageID

Identifier of the page to replace. The values for this parameter for control panels can be found in the CPLEXT.H header file.

lpfnReplacePage

Pointer to a function that the property sheet handler calls to replace a page to the property sheet. The function takes a property sheet handle returned by the CreatePropertySheetPage function and the lParam parameter passed to the ReplacePage method.

lParam

Parameter to pass to the function specified by lpfnReplacePage.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

To replace a page, a property sheet handler fills a PROPSHEETPAGE structure, calls CreatePropertySheetPage, and then calls the function specified by lpfnReplacePage.

See Also

CreatePropertySheetPage, IShellPropSheetExt, PROPSHEETPAGE


IShellExtInit

Designates an interface used to initialize a property sheet extension, context menu extension, or drag and drop handler.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IShellExtInit Method	Description
Initialize	Initializes the shell extension.


IShellExtInit::Initialize

Initializes a property sheet extension, context menu extension, or drag and drop handler.

HRESULT STDMETHODCALLTYPE Initialize(

LPSHELLEXTINIT pIface,
LPCITEMIDLIST pidlFolder,
LPDATAOBJECT lpdobj,
HKEY hkeyProgID
);
Parameters

pIface

Pointer to the IShellExtInit interface. In C++, this parameter is implicit.

pidlFolder

Pointer to an structure ITEMIDLIST (item identifier list) that uniquely identifies a folder. This parameter is NULL for property sheet extensions and context menu extensions. For non-default drag and drop menu extensions, this parameter must specify the target folder.

lpdobj

Pointer to an IDataObject interface object that can be used to retrieve the objects being acted upon.

hkeyProgID

Registry key for the file object or folder type.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

This is the first method that the shell calls after it creates an instance of a property sheet extension, context menu extension, or drag and drop handler.

The meanings of some parameters depend on the extension type. For drag and drop handlers, the item identifier list specifies the destination folder (the drop target), the IDataObject interface identifies the items being dropped, and the registry key specifies the file class of the destination folder.

For property sheet extensions and context menu extensions, the item identifier list specifies the folder that contains the selected file objects, the IDataObject interface identifies the selected file objects, and the registry key specifies the file class of the file object that has the focus.

See Also

IShellExtInit, ITEMIDLIST


IShellLink

Designates an interface that allows an application to create and resolve shell links.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IShellLink Methods	Description
GetArguments	Retrieves the command-line arguments associated with a shell link object.
GetDescription	Retrieves the description string for a shell link object.
GetHotkey	Retrieves the hot key for a shell link object.
GetIconLocation	Retrieves the location (path and index) of the icon for a shell link object.
GetIDList	Retrieves the list of item identifiers for a shell link object.
GetPath	Retrieves the path and filename of a shell link object.
GetShowCmd	Retrieves the show (SW_) command for a shell link object.
GetWorkingDirectory	Retrieves the name of the working directory for a shell link object.
Resolve	Resolves a shell link by searching for the shell link object and updating the shell link path and its list of identifiers (if necessary).
SetArguments	Sets the command-line arguments associated with a shell link object.
SetDescription	Sets the description string for a shell link object.
SetHotkey	Sets the hot key for a shell link object.
SetIconLocation	Sets the location (path and index) of the icon for a shell link object.
SetIDList	Sets the list of item identifiers for a shell link object.
SetPath	Sets the path and filename of a shell link object.
SetRelativePath	Sets the relative path for a shell link object.
SetShowCmd	Sets the show (SW_) command for a shell link object.
SetWorkingDirectory	Sets the name of the working directory for a shell link object.


IShellLink::GetArguments

Retrieves the command-line arguments associated with a shell link object.

HRESULT STDMETHODCALLTYPE GetArguments(

ISHELLLINK FAR * pShlLnk,
LPSTR pszArgs,
int cchMaxPath
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszArgs

Pointer to a buffer that receives the command-line arguments.

cchMaxPath

Maximum number of characters to copy to the buffer pointed to by pszArgs.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::GetDescription

Retrieves the description string for a shell link object.

RESULT STDMETHODCALLTYPE GetDescription(

ISHELLLINK FAR * pShlLnk,
LPSTR pszName,
int cchMaxName
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszName

Pointer to a buffer that receives the description string.

cchMaxName

Maximum number of characters to copy to the buffer pointed to by pszName.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::GetHotkey

Retrieves the hot key for a shell link object.

HRESULT STDMETHODCALLTYPE GetHotkey(

ISHELLLINK FAR * pShlLnk,
WORD *pwHotkey
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pwHotkey

Pointer to the hot key. The virtual-key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the following values:

HOTKEYF_ALT	ALT key
HOTKEYF_CONTROL	CTRL key
HOTKEYF_EXT	Extended key
HOTKEYF_SHIFT	SHIFT key
Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::GetIconLocation

Retrieves the location (path and index) of the icon for a shell link object.

HRESULT STDMETHODCALLTYPE GetIconLocation(

ISHELLLINK FAR * pShlLnk,
LPSTR pszIconPath,
int cchIconPath,
int *piIcon
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszIconPath

Pointer to a buffer that receives the path of the file containing the icon.

cchIconPath

Maximum number of characters to copy to the buffer pointed to by pszIconPath.

piIcon

Pointer to a value that receives the index of the icon.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::GetIDList

Retrieves the list of item identifiers for a shell link object.

HRESULT STDMETHODCALLTYPE GetIDList(

ISHELLLINK FAR * pShlLnk,
LPITEMIDLIST * ppidl
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

ppidl

Pointer to a pointer to a list of item identifiers.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::GetPath

Retrieves the path and filename of a shell link object.

HRESULT STDMETHODCALLTYPE GetPath(

IShellLink FAR * pShlLnk,
LPSTR pszFile,
int cchMaxPath,
WIN32_FIND_DATA *pfd,
DWORD fFlags
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszFile

Pointer to a buffer that receives the path and filename of the shell link object.

cchMaxPath

Maximum number of bytes to copy to the buffer pointed to by pszFile.

pfd

Pointer to a WIN32_FIND_DATA structure that contains information about the shell link object.

fFlags

Flags that specify the type of path information to retrieve. This parameter can be a combination of the following values:

SLGP_SHORTPATH	Retrieves the standard short (8.3) filename.
SLGP_UNCPRIORITY	Retrieves the Universal Naming Convention (UNC) path name of the file.
Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink, WIN32_FIND_DATA


IShellLink::GetShowCmd

Retrieves the show command for a shell link object.

HRESULT STDMETHODCALLTYPE GetShowCmd(

ISHELLLINK FAR * pShlLnk,
int *piShowCmd
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

piShowCmd

Pointer to the show command. For a list of show commands, see the description of the ShowWindow function.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink, ShowWindow


IShellLink::GetWorkingDirectory

Retrieves the name of the working directory for a shell link object.

HRESULT STDMETHODCALLTYPE GetWorkingDirectory(

ISHELLLINK FAR * pShlLnk,
LPSTR pszDir,
int cchMaxPath
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszDir

Pointer to a buffer that receives the name of the working directory.

cchMaxPath

Maximum number of characters to copy to the buffer pointed to by pszDir. The name of the working directory is truncated if it is longer than the maximum specified by this parameter.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::Resolve

Resolves a shell link. The system searches for the shell link object and updates the shell link path and its list of identifiers (if necessary).

HRESULT STDMETHODCALLTYPE Resolve(

ISHELLLINK FAR * pShlLnk,
HWND hwnd,
DWORD fFlags
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

hwnd

Handle of a window that the shell uses as the parent window for a dialog box. The shell displays the dialog box if it needs to prompt the user for more information while resolving a shell link.

fFlags

Action flags. This parameter can be a combination of the following values:

SLR_ANY_MATCH	Resolves the link, displaying a dialog box if the system needs information from the user.
SLR_NO_UI	Prevents the shell from displaying a dialog box if it cannot resolve the shell link. When this flag is specified, the high-order word of fFlags specifies a timeout duration, in milliseconds. The function returns if the link cannot be resolved within the timeout duration. If the high-order word is set to zero, the timeout duration defaults to 3000 milliseconds (3 seconds).
SLR_UPDATE	Directs the shell to update the path to the link and the list of identifiers if the link object has been changed. If this value is used, it is not necessary to call the IPersistFile::IsDirty method to determine whether the link object has changed.
Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

When this method is called, the system retrieves the path associated with the current link object and searches for the object in that path. If the system finds the object, it resolves the link. If the system cannot find the object, it looks in the same directory for an object with the same file creation time and attributes, but with a different name. This type of search resolves a link to an object that has been renamed.

If the system still cannot find the link object, it searches the subdirectories of the current directory. It does a recursive search of the directory tree looking for a match with either the same name or creation time. If it does not find a match after that, the shell displays a dialog box prompting the user for a location. An application can suppress the dialog box by specifying the SLR_NO_UI value in a call to this method.

See Also

IShellLink


IShellLink::SetArguments

Sets the command-line arguments for a shell link object.

HRESULT STDMETHODCALLTYPE SetArguments(

ISHELLLINK FAR * pShlLnk,
LPCSTR pszArgs
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszArgs

Pointer to a buffer that contains the new command-line arguments.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

This method is useful when creating a link to an application that takes special flags as arguments, such as a compiler.

See Also

IShellLink


IShellLink::SetDescription

Sets the description for a shell link object. The description can be any application-defined string.

HRESULT STDMETHODCALLTYPE SetDescription(

ISHELLLINK FAR * pShlLnk,
LPCSTR pszName
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszName

Pointer to a buffer containing the new description string.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::SetHotkey

Sets a hot key for a shell link object.

HRESULT STDMETHODCALLTYPE SetHotkey(

ISHELLLINK FAR * pShlLnk,
WORD wHotkey
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

wHotkey

Hot key. The virtual-key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the values specified in the description of the IShellLink::GetHotkey method.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

Setting a hot key allows the user to activate the object by pressing a particular combination of keys.

See Also

IShellLink, IShellLink::GetHotkey


IShellLink::SetIconLocation

Sets the location (path and index) of the icon for a shell link object.

HRESULT STDMETHODCALLTYPE SetIconLocation(

ISHELLLINK FAR * pShlLnk,
LPCSTR pszIconPath,
int iIcon
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszIconPath

Pointer to a buffer that contains the path of the file containing the icon.

iIcon

Index of the icon.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::SetIDList

Sets the list of item identifiers for a shell link object.

HRESULT STDMETHODCALLTYPE SetIDList(

ISHELLLINK FAR * pShlLnk,
LPCITEMIDLIST pidl
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pidl

Pointer to a list of item identifiers.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

This method is useful when an application needs to set a shell link to an object that is not a file, such as a Control Panel application, a printer, or another computer.

See Also

IShellLink


IShellLink::SetPath

Sets the path and filename of a shell link object.

HRESULT STDMETHODCALLTYPE SetPath(

ISHELLLINK FAR * pShlLnk,
LPCSTR pszFile
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszFile

Pointer to a buffer that contains the new path.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::SetRelativePath

Sets the relative path to the shell link object.

HRESULT STDMETHODCALLTYPE SetRelativePath(

ISHELLLINK FAR * pShlLnk,
LPCSTR pszPathRel,
LPCITEMIDLIST pidlRel
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszPathRel

Pointer to a buffer that contains the new relative path.

pidlRel

Pointer to a list of item identifiers that identify the object.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink


IShellLink::SetShowCmd

Sets the show command for a shell link object. The show command sets the initial show state of the window.

HRESULT STDMETHODCALLTYPE SetShowCmd(

ISHELLLINK FAR * pShlLnk,
int iShowCmd
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

iShowCmd

Show command. For a list of the show commands, see the description of the ShowWindow function.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellLink, ShowWindow


IShellLink::SetWorkingDirectory

Sets the name of the working directory for a shell link object.

HRESULT STDMETHODCALLTYPE SetWorkingDirectory(

ISHELLLINK FAR * pShlLnk,
LPCSTR pszDir
);
Parameters

pShlLnk

Pointer to the IShellLink interface. In C++, this parameter is implicit.

pszDir

Pointer to a buffer that contains the name of the new working directory.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

The working directory must be set only if the object requires it to be set. For example, if an application creates a shell link to a Microsoft Word document that uses a template that resides in a different directory, the application would use this method to set the working directory.

See Also

IShellLink


IShellFolder

Designates an interface implemented by the shell and used to determine the contents of a folder.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IShellFolder Methods	Description
ParseDisplayName	Translates a display name into an item identifier list.
EnumObjects	Enumerates the objects in the folder.
BindToObject	Retrieves the IShellFolder interface for the specified subfolder.
BindToStorage	Reserved; this function is not currently implemented.
CompareIDs	Compares two item identifier lists and returns the result.
CreateViewObject	Reserved for use by the shell; do not use.
GetAttributesOf	Retrieves the attributes of the specified file object or subfolder.
GetUIObjectOf	Creates an OLE interface that can be used to carry out operations on a file object or subfolder.
GetDisplayNameOf	Retreives the display name of a file object or subfolder.
SetNameOf	Sets the display name of the specified file object or subfolder and changes its identifier accordingly.


IShellFolder::BindToObject

Creates an IShellFolder object for a subfolder.

HRESULT STDMETHODCALLTYPE BindToObject(

LPSHELLFOLDER pIface,
LPCITEMIDLIST pidl,
LPBC pbcReserved,
REFIID riid,
LPVOID *ppvOut
);
Parameters

pIface

Pointer to the IShellFolder interface. In C++, this parameter is implicit.

pidl

Pointer to an ITEMIDLIST structure that identifies the subfolder relative to its parent folder.

pbcReserved

Reserved; applications should specify NULL for this parameter.

riid

Identifier of the interface to return. This parameter must point to the IID_IShellFolder interface identifier.

ppvOut

Address that receives the interface pointer. If an error occurs, a NULL pointer is returned in this address.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellFolder, ITEMIDLIST


IShellFolder::BindToStorage

This method is reserved for future use and is not currently implemented.


IShellFolder::CompareIDs

Determines the relative ordering of two file objects or folders, given their item identifier lists.

HRESULT STDMETHODCALLTYPE CompareIDs(

LPSHELLFOLDER pIface,
LPARAM lParam,
LPCITEMIDLIST pidl1,
LPCITEMIDLIST pidl2
);
Parameters

pIface

Pointer to the IShellFolder interface. In C++, this parameter is implicit.

lParam

Value specifying the type of comparison to perform. The calling application should always specify zero, indicating that the two items should be sorted by name.

pidl1 and pidl2

Addresses of two ITEMIDLIST structures that uniquely identify the items to be compared. Both item identifier lists are relative to the parent folder.

Return Value

Returns a handle to a result code. If this method is successful, the CODE field of the status code (SCODE) has the following meaning:

CODE field	Meaning
Less than zero	The first item should precede the second (pidl1 < pidl2).
Greater than zero	The first item should follow the second (pidl1 > pidl2)
Zero	The two items are the same (pidl1 = pidl2).
See Also

IShellFolder, ITEMIDLIST


IShellFolder::CreateViewObject

This method is reserved for use by the shell and should not be called by applications.


IShellFolder::EnumObjects

Creates an item enumeration object (an IEnumIDList interface) that can be used to enumerate the contents of a folder.

HRESULT STDMETHODCALLTYPE EnumObjects(

LPSHELLFOLDER pIface,
HWND hwndOwner,
DWORD grfFlags,
LPENUMIDLIST *ppenumIDList
);
Parameters

pIface

Pointer to the IShellFolder interface. In C++, this parameter is implicit.

hwndOwner

Handle of the owner window that the client should specify if it displays a dialog box or message box.

grfFlags

Flags determining which items to enclude in the enumeration. For a list of possible values, see the description of the SHCONTF type.

ppenumIDList

Address that receives a pointer to the IEnumIDList interface created by this method. If an error occurs, a NULL pointer is returned in this address.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

The calling application must free the returned IEnumIDList object by calling its Release method.

This method is similar to the IOleContainer::EnumObjects method defined by OLE.

See Also

IEnumIDList, IShellFolder


IShellFolder::GetAttributesOf

Retrieves the attributes of one or more file objects or subfolders.

HRESULT STDMETHODCALLTYPE GetAttributesOf(

LPSHELLFOLDER pIface,
UINT cidl,
LPCITEMIDLIST *apidl,
ULONG *rgfInOut
);
Parameters

pIface

Pointer to the IShellFolder interface. In C++, this parameter is implicit.

cidl

Number of file objects to get the attributes of.

apidl

Pointer to an array of pointers to ITEMIDLIST structures, each of which uniquely identifies a file object relative to the parent folder. Each ITEMIDLIST structure must contain exactly one SHITEMID structure followed by a terminating zero.

rgfInOut

Address of an array of values that specify file object attributes. The calling application should initialize each array element by specifying which file object attributes to retrieve.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

This method returns the actual attributes of each file object in the corresponding array element; it may return all attributes or just the requested attributes.

The following tables list the attribute flags that may be returned by this method. File object attributes include capability flags, display attributes, contents flags, and miscellaneous attributes.

A file object's capability flags may include zero or more of the following values:

SFGAO_CANCOPY	The specified file objects or folders can be copied (same value as the DROPEFFECT_COPY flag).
SFGAO_CANDELETE	The specified file objects or folders can be deleted.
SFGAO_CANLINK	It is possible to create shortcuts for the specified file objects or folders (same value as the DROPEFFECT_LINK flag).
SFGAO_CANMOVE	The specified file objects or folders can be moved (same value as the DROPEFFECT_MOVE flag).
SFGAO_CANRENAME	The specified file objects or folders can be renamed.
SFGAO_CAPABILITYMASK	Mask for the capability flags.
SFGAO_DROPTARGET	The specified file objects or folders are drop targets.
SFGAO_HASPROPSHEET	The specified file objects or folders have property sheets.
A file object's display attributes may include zero or more of the following values:

SFGAO_DISPLAYATTRMASK	Mask for the display attributes.
SFGAO_GHOSTED	The specified file objects or folders should be displayed using a ghosted icon.
SFGAO_LINK	The specified file objects are shortcuts.
SFGAO_READONLY	The specified file objects or folders are read-only.
SFGAO_SHARE	The specified folders are shared.
A file object's contents flags may include zero or more of the following values:

SFGAO_CONTENTSMASK	Mask for the contents attributes.
SFGAO_HASSUBFOLDER	The specified folders have subfolders (and are, therefore, expandable in the left pane of Windows Explorer).
A file object may have zero or more of the following miscellaneous attributes:

SFGAO_FILESYSTEM	The specified folders or file objects are part of the file system (that is, they are files, directories, or root directories).
SFGAO_FILESYSANCESTOR	The specified folders contain one or more file system folders.
SFGAO_FOLDER	The specified items are folders.
SFGAO_REMOVABLE	The specified file objects or folders are on removable media.
SFGAO_VALIDATE	Validate cached information.
See Also

IShellFolder, ITEMIDLIST, SHITEMID


IShellFolder::GetDisplayNameOf

Retrieves the display name for the specified file object or subfolder.

HRESULT STDMETHODCALLTYPE GetDisplayNameOf(

LPSHELLFOLDER pIface,
LPCITEMIDLIST pidl,
DWORD uFlags,
LPSTRRET lpName
);
Parameters

pIface

Pointer to the IShellFolder interface. In C++, this parameter is implicit.

pidl

Pointer to an ITEMIDLIST structure that uniquely identifes the file object or subfolder relative to the parent folder.

uFlags

Value indicating the type of display name to return. For a list of possible values, see the description of the SHGNO enumerated type.

lpName

Pointer to a STRRET structure in which to return the display name. The string returned in this structure depends on the type of display name requested.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellFolder, ITEMIDLIST, STRRET


IShellFolder::GetUIObjectOf

Returns an interface that can be used to carry out actions on the specified file objects or folders — typically, to create context menus or carry out drag and drop operations.

HRESULT STDMETHODCALLTYPE GetUIObjectOf(

LPSHELLFOLDER pIface,
HWND hwndOwner,
UINT cidl,
LPCITEMIDLIST *apidl,
REFIID riid,
UINT *prgfReserved,
LPVOID *ppvOut
);
Parameters

pIface

Pointer to the IShellFolder interface. In C++, this parameter is implicit.

hwndOwner

Handle of the owner window that the client should specify if it displays a dialog box or message box.

cidl

Number of file objects or subfolders specified by apidl.

apidl

Pointer to an array of pointers to ITEMIDLIST structures, each of which uniquely identifies a file object or subfolder relative to the parent folder. Each item identifier list must contain exactly one SHITEMID structure followed by a terminating zero.

riid

Identifier of the interface to return. This parameter can be a pointer to the IID_IExtractIcon, IID_IContextMenu, IID_IDataObject, or IID_IDropTarget interface identifier.

prgfReserved

Reserved for future versions of Windows; must be NULL.

ppvOut

Address that receives the interface pointer. If an error occurs, a NULL pointer is returned in this address.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellFolder, ITEMIDLIST, SHITEMID


IShellFolder::ParseDisplayName

Translates a file object or folder's display name into an item identifier.

HRESULT STDMETHODCALLTYPE IShellFolder::ParseDisplayName(

LPSHELLFOLDER pIface,
WND hwndOwner,
LPBC pbcReserved,
LPWSTR lpwszDisplayName,
ULONG *pchEaten,
LPITEMIDLIST *ppidl,
ULONG *pdwAttributes
);
Parameters

pIface

Pointer to the IShellFolder interface. In C++, this parameter is implicit.

hwndOwner

Handle of the owner window that the client should specify if it displays a dialog box or message box.

pbcReserved

Reserved; this parameter is always NULL.

lpwszDisplayName

Pointer to a null-terminated Unicode string specifying the display name. This parameter must be a display name for parsing — that is, a display name retrieved using the SHGDN_FORPARSING value.

pchEaten

Pointer to an unsigned long value that receives the number of characters of the display name that were parsed.

ppidl

Address that receives a pointer to the new item identifier list for the object. If an error occurs, a NULL is returned in this address.

The returned item identifier list specifies the relative path (from the parent folder) that corresponds to the specified display name. It contains only one SHITEMID structure followed by a terminating zero.

pdwAttributes

Address that receives the attributes of the file object.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

Remarks

This method is similar to the IParseDisplayName::IParseDisplayName method defined by OLE.

See Also

IShellFolder, IShellLink, SHITEMID


IShellFolder::SetNameOf

Changes the name of a file object or subfolder, changing its item identifier in the process.

HRESULT STDMETHODCALLTYPE SetNameOf(

LPSHELLFOLDER pIface,
HWND hwndOwner,
LPCITEMIDLIST pidl,
LPCOLESTR lpszName,
DWORD uFlags,
LPITEMIDLIST *ppidlOut
);
Parameters

pIface

Pointer to the IShellFolder interface. In C++, this parameter is implicit.

hwndOwner

Handle of the owner window that the client should specify if it displays a dialog box or message box.

pidl

Pointer to an ITEMIDLIST structure that uniquely identifies the file object or subfolder relative to the parent folder.

lpszName

Pointer to a null-terminated string that specifies the new display name.

uFlags

Value indicating the type of name specified by the lpszName parameter. For a list of possible values, see the description of the SHCONTF enumerated type.

ppidlOut

Address in which the method returns a pointer to the new ITEMIDLIST structure. This parameter can be NULL, and in that case, the method does not return the new ITEMIDLIST for the object.

If this parameter is not NULL, this method frees the specified ITEMIDLIST structure and allocates a new one using the task allocator. The calling application is responsible for freeing the new ITEMIDLIST structure. If an error occurs, the method returns NULL in this address.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IShellFolder, ITEMIDLIST


IEnumIDList

Designates an interface used to enumerate item identifiers. The IShellFolder::EnumObjects method creates an IEnumIDList interface.

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IEnumIDList Methods	Description
Clone	Creates a new item enumeration object having the same contents and state as the given one.
Next	Retrieves one or more item identifiers and advances the current position.
Reset	Returns to the beginning of the enumeration sequence.
Skip	Skips over one or more items in the enumeration sequence.


IEnumIDList::Clone

Creates a new item enumeration object with the same contents and state as the current one.

HRESULT STDMETHODCALLTYPE Clone(

IEnumIDList FAR * pEnumIDList,
IEnumIDList **ppenum
);
Parameters

pEnumIDList

Pointer to the IEnumIDList interface. In C++, this parameter is implicit.

ppenum

Address that receives a pointer to the new enumeration object. The calling application must eventually free the new object by calling its Release method.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

This method makes it possible to record a particular point in the enumeration sequence and then return to that point at a later time.

See Also

IEnumIDList


IEnumIDList::Next

Retrieves the specified number of item identifiers in the enumeration sequence and advances the current position.

HRESULT STDMETHODCALLTYPE Next(

EnumIDList FAR * pEnumIDList,
LONG celt,
PITEMIDLIST *rgelt,
LONG *pceltFetched
);
Parameters

EnumIDList

Address of the IEnumIDList interface. In C++, this parameter is implicit.

celt

Number of item identifiers to retrieve. If the number of identifiers requested is more than remains in the sequence, only the remaining elements are retrieved.

rgelt

Address of an array in which to return the item identifiers. The calling application is responsible for freeing the returned item identifier lists by using the shell's allocator.

pceltFetched

Pointer to a value that receives a count of the item identifiers actually returned in rgelt. This parameter can be NULL if (and only if) celt is one.

Return Value

Returns NOERROR if successful, S_FALSE if there are no more items in the enumeration sequence, or an OLE-defined error value if an error occurs.

If this method returns any value other than NOERROR, no entries in the rgelt array are valid on exit. They are all in an indeterminate state.

See Also

IEnumIDList


IEnumIDList::Reset

Returns to the beginning of the enumeration sequence.

HRESULT STDMETHODCALLTYPE Reset(

IEnumIDList FAR * pEnumIDList
);
Parameter

pEnumIDList

Pointer to the IEnumIDList interface. In C++, this parameter is implicit.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IEnumIDList


IEnumIDList::Skip

Skips over the specified number of elements in the enumeration sequence.

HRESULT STDMETHODCALLTYPE Skip(

IEnumIDList FAR * pEnumIDList,
ULONG celt
);
Parameters

pEnumIDList

Pointer to the IEnumIDList interface. In C++, this parameter is implicit.

celt

Number of item identifiers to skip.

Return Value

Returns NOERROR if successful or an OLE-defined error value otherwise.

See Also

IEnumIDList


IRichEditOle

Specifies an interface used by the client of a rich text edit control to carry out OLE-related operations. The IRichEditOle interface has the following methods:

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IRichEditOle Methods	Description
GetClientSite	Retrieves an IOleClientSite interface to use when creating a new object.
GetObjectCount	Returns the number of objects contained in a rich edit control.
GetLinkCount	Returns the number of objects in a rich edit control that are links.
GetObject	Returns information from a REOBJECT structure about an object in a rich edit control.
InsertObject	Inserts an object into a rich edit control.
ConvertObject	Converts an object to a new type.
ActivateAs	Unloads objects of the old class, telling OLE to treat those objects as objects of the new class, and reloading the objects.
SetHostNames	Sets the "host names" to be given to objects as they are inserted to a rich edit control.
SetLinkAvailable	Sets the value of the link available bit in the object's flags.
SetDvaspect	Sets the aspect that a rich edit control uses to draw an object.
HandsOffStorage	Tells a rich edit control to release its reference to the storage interface associated with the specified object.
SaveCompleted	Tells a rich edit control that the most recent save operation has been completed, and that it should hold on to a different storage for the object.
InPlaceDeactivate	Tells a rich edit control to deactivate the currently active in-place object, if any.
ContextSensitiveHelp	Tells a rich edit control to transition into or out of context-sensitive help mode.
GetClipboardData	Retrieves a clipboard object for a range in an edit control.
ImportDataObject	Imports a clipboard object into a rich edit control, replacing the current selection.


IRichEditOle::ActivateAs

Handles OLE "Activate As" behavior by unloading all objects of the old class, telling OLE to treat those objects as objects of the new class, and reloading the objects. If objects cannot be reloaded, they are deleted.

HRESULT ActivateAs(

REFCLSID rclsid,
REFCLSID rclsidAs
);
Parameters

rclsid

Class identifier of the old class.

rclsidAs

Class identifier of the new class.

Return Value

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or an SCODE returned from OLE.


IRichEditOle::ContextSensitiveHelp

Tells a rich edit control that it should transition into or out of context sensitive help mode. A rich edit control calls the ContextSensitiveHelp method of any in place object which is currently active if a state change is occuring.

HRESULT ContextSensitiveHelp(

BOOL fEnterMode
);
Parameter

fEnterMode

TRUE if entering context sensitive help mode; otherwise, FALSE.

Return Value

Returns success status. Can use GetScode to retrieve an SCODE. Can be S_OK on success or some other value returned by OLE.


IRichEditOle::ConvertObject

Converts an object to a new type. This call does reload the object but does not force an update; the caller must do this.

HRESULT ConvertObject(

LONG iob,
REFCLSID rclsidNew,
LPCSTR lpstrUserTypeNew
);
Parameters

iob

Index of the object to convert. If this parameter is REO_IOB_SELECTION, the selected object is to be converted.

rclsidNew

Class identifier of the class to which the object is to be converted.

szUserTypeNew

User-visible type name of the class to which the object is to be converted.

Return Value

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if the index is invalid, or an SCODE returned from OLE.


IRichEditOle::GetClientSite

Retrieves an IOleClientSite interface to be used when creating a new object. All objects inserted into a rich edit control must use client site interfaces returned by this function. A client site may be used with exactly one object.

HRESULT GetClientSite(

LPOLECLIENTSITE FAR * lplpolesite
);
Parameter

lplpoleclientsite

Pointer to the pointer variable that receives the address of the IOleClientSite interface.

Return Value

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_OUTOFMEMORY if memory could not be allocated for the client site.


IRichEditOle::GetClipboardData

Retrieves a clipboard object for a range in an edit control.

HRESULT GetClipboardData(

CHARRANGE FAR * lpchrg,
DWORD reco,
LPDATAOBJECT FAR * lplpdataobj
);
Parameters

lpchrg

Pointer to the CHARRANGE structure specifying the range to create the clipboard object for.

reco

Clipboard operation flag. Can be one of these values.

RECO_COPY	Copy to the clipboard.
RECO_CUT	Cut to the clipboard.
RECO_DRAG	Drag operation (drag and drop)
RECO_DROP	Drop operation (drag and drop).
RECO_PASTE	Paste from the clipboard.
lplpdataobj

Pointer to the DATAOBJECT structure that receives the clipboard object representing the range specified in the lpchrg parameter.

Return Value

Returns success status.


IRichEditOle::GetLinkCount

Returns the number of objects in a rich edit control that are links.

LONG GetLinkCount();

Return Value

Returns the number of links.


IRichEditOle::GetObject

Returns information from a REOBJECT structure about an object in a rich edit control.

HRESULT GetObject(

LONG iob,
REOBJECT FAR * lpreobject,
DWORD dwFlags
);
Parameters

iob

Zero-based index specifying which object to return information about. If this parameter is REO_IOB_USE_CP, information about the object at the character position specified by the REOBJECT structure is returned.

lpreobject

Pointer to a REOBJECT structure that receives information about the object. The reference count of the interfaces returned in this structure has been incremented; it is the responsibility of the caller to use the Release function to decrement the count.

dwFlags

Operation flags specifying which interfaces to return in the structure. Can be a combination of these values:

REO_GETOBJ_POLEOBJ	Get OLE object interface.
REO_GETOBJ_PSTG	Get Storage interface.
REO_GETOBJ_POLESITE	Get OLE site interface.
REO_GETOBJ_NO_INTERFACES	Get no interfaces.
REO_GETOBJ_ALL_INTERFACES	Get all interfaces.
Return Value

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if no buffer for the REOBJECT structure was given, or the iob or character position is invalid.


IRichEditOle::GetObjectCount

Returns the number of objects currently contained in a rich edit control.

LONG GetObjectCount();

Return Value

Returns the number of objects.


IRichEditOle::HandsOffStorage

Tells a rich edit control to release its reference to the storage interface associated with the specified object. This call does not call the object's IPersistStorage::HandsOffStorage method, the caller must do that.

HRESULT HandsOffStorage(

LONG iob
);
Parameter

iob

Index of the object whose storage is to be released. If this parameter is REO_IOB_SELECTION, the selected object's storage is to be released.

Return Value

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if the index is invalid.


IRichEditOle::ImportDataObject

Imports a clipboard object into a rich edit control, replacing the current selection.

HRESULT ImportDataObject(

LPDATAOBJECT lpdataobj,
CLIPFORMAT cf,
HGLOBAL hMetaPict
);
Parameters

lpdataobj

Pointer to a DATAOBJECT structure specifying the clipboard object to import.

cf

Clipboard format to use or zero to use the best available format.

hMetaPict

Handle to a metafile containing the icon view of an object. Used only if the DVASPECT_ICON display aspect is required by Paste Special command.

Return Value

Returns success status.


IRichEditOle::InPlaceDeactivate

Tells a rich edit control to deactivate the currently active in-place object, if any.

HRESULT InPlaceDeactivate();

Return Value

Returns success status. Can use GetScode to retrieve an SCODE. Can be S_OK on success or some other value returned by OLE. No error is returned if there is no active in-place object.


IRichEditOle::InsertObject

Inserts an object into a rich edit control.

HRESULT InsertObject(

REOBJECT FAR * lpreobject
);
Parameter

lpreobject

Pointer to a REOBJECT structure containing the object information and interfaces. The rich edit control automatically increments the reference count for the interfaces if it holds onto them, so the caller can safely release the interfaces if not needed.

Return Value

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_OUTOFMEMORY if memory could not be allocated to insert the object.

If the cp member of the REOBJECT structure is REO_CP_SELECTION, the selection is replaced with the specified object.


IRichEditOle::SaveCompleted

Tells a rich edit control that the most recent save operation has been completed, and that it should hold on to a different storage for the object.

HRESULT SaveCompleted(

LONG iob,
LPSTORAGE lpstg
);
Parameters

iob

Index of the object whose storage is being specified. If this parameter is REO_IOB_SELECTION, the selected object is used.

pstg

New storage for the object. If the storage is not NULL, the rich edit control releases any storage it is currently holding for the object, and uses this new storage instead.

Return Value

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if the index is invalid.


IRichEditOle::SetDvaspect

Sets the aspect that a rich edit control uses to draw an object. This call does not change the drawing information cached in the object; this must be done by the caller. The call does cause the object to be redrawn.

HRESULT SetDvaspect(

LONG iob,
DWORD dvaspect
);
Parameters

iob

Index of the object whose aspect is to be set. If this parameter is REO_IOB_SELECTION, the aspect of the selected object is to be set.

dvaspect

Aspect to use when drawing. The values are defined by OLE2.

Return Value

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if the index is invalid.


IRichEditOle::SetHostNames

Sets the "host names" to be given to objects as they are inserted to a rich edit control. The host names are used in the user interface of servers to describe the container context of opened objects.

HRESULT SetHostNames(

LPCSTR lpstrContainerApp,
LPCSTR lpstrContainerObj
);
Parameters

szContainerApp

Null-terminated name of the container application.

szContainerObj

Null-terminated name of the container document or object.

Return Value

Returns success status. Use GetScode to retrieve an scode. Can be S_OK on success or E_OUTOFMEMORY if memory could not be allocated to remember the strings.


IRichEditOle::SetLinkAvailable

Sets the value of the link available bit in the object's flags. The link available bit defaults to TRUE. It should be set to FALSE if any errors occur on the link which would indicate problems connecting to the linked object or application. When those problems are repaired, the bit should be set to TRUE again.

HRESULT SetLinkAvailable(

LONG iob,
BOOL fAvailable
);
Parameters

iob

Index of object whose bit is to be set. If this parameter is REO_IOB_SELECTION, the bit on the selected object is to be set.

fAvailable

Value to set the bit to. Can be TRUE or FALSE.

Return Value

Returns success status. Use GetScode to retrieve an SCODE. Can be S_OK on success or E_INVALIDARG if the index is invalid.


IRichEditOleCallback

Specifies an interface used by a rich text edit control to retrieve OLE-related information from its client. A rich edit control's client is responsible for implementing this interface and assigning it to the control by using the EM_SETOLEINTERFACE message. The IRichEditOleCallback interface has the following methods:

Methods in Vtable Order

IUnknown Methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments reference count.
Release	Decrements reference count.
IRichEditOleCallback Methods	Description
GetNewStorage	Provides storage for a new object pasted from the clipboard or read in from an RTF stream.
GetInPlaceContext	Provides the application and document level interfaces and information required to support in-place activation.
ShowContainerUI	Tells the application whether to display its container user interface.
QueryInsertObject	Queries the application as to whether an object should be inserted.
DeleteObject	Notification that an object is about to be deleted from a rich edit control.
QueryAcceptData	Called on a paste or drag to determine if the data pasted/dragged should be accepted.
ContextSensitiveHelp	Tells the application that it should transition into or out of context sensitive help mode.
GetClipboardData	Allows the client to supply its own clipboard object.
GetDragDropEffect	Allows the client to specify the effects of a drop operation.
GetContextMenu	Queries the application for a context menu to use on a right mouse button down event.


IRichEditOleCallback::ContextSensitiveHelp

Tells the application that it should transition into or out of context sensitive help mode. This member should implement the functionality described for IOleInPlaceSite::ContextSensitiveHelp (as described in the OLE documentation).

HRESULT ContextSensitiveHelp(

BOOL fEnterMode
);
Parameter

fEnterMode

TRUE if entering context sensitive help mode; otherwise, FALSE.

Return Value

Returns success status.


IRichEditOleCallback::DeleteObject

Notification that an object is about to be deleted from a rich edit control. The object is not necessarily being released when this member is called.

HRESULT DeleteObject(

LPOLEOBJECT lpoleobj
);
Parameter

lpoleobj

Pointer to the OLEOBJECT structure specifying the object that is being deleted.

Return Value

No return value.


IRichEditOleCallback::GetClipboardData

Allows the client to supply its own clipboard object.

HRESULT GetClipboardData(

CHARRANGE FAR * lpchrg,
DWORD reco,
LPDATAOBJECT FAR * lplpdataobj
);
Parameters

lpchrg

Pointer to the CHARRANGE structure specifying the range the clipboard object is for.

reco

Clipboard operation flag. Can be one of these values.

RECO_COPY	Copy to the clipboard.
RECO_CUT	Cut to the clipboard.
RECO_DRAG	Drag operation (drag and drop)
RECO_DROP	Drop operation (drag and drop).
RECO_PASTE	Paste from the clipboard.
lplpdataobj

Pointer to the pointer variable that receives the address of the IDataObject implementation representing the range specified in the lpchrg parameter. The value of lppdataobj is ignored if an error is returned.

Return Value

Returns success status. If the SCODE of the return value is E_NOTIMPL, the rich edit control creates its own clipboard object. If the SCODE of the return value is a failure other than E_NOTIMPL the operation fails.


IRichEditOleCallback::GetContextMenu

Queries the application for a context menu to use on a right mouse down.

HRESULT GetContextMenu(

WORD seltyp,
LPOLEOBJECT lpoleobj,
CHARRANGE FAR * lpchrg,
HMENU FAR * lphmenu
);
Parameters

seltype

selection type

lpoleobj

Pointer to a OLEOBJECT structure specifying the first selected OLE object if the selection contains one or more objects NULL otherwise. The caller must use AddRef to increment the object reference count if it holds onto it.

lpchrg

Pointer to a CHARRANGE structure containing the current selection.

lphmenu

Pointer to a variable containing the handle of a context menu to use. This parameter is ignored if an error is returned. A rich edit control destroys the menu when it is finished with it so the client should not.

Return Value

Returns success status.


IRichEditOleCallback::GetDragDropEffect

Allows the client to specify the effects of a drop operation.

HRESULT GetDragDropEffect(

BOOL fDrag,
DWORD grfKeyState,
LPDWORD pdwEffect
);
Parameters

fDrag

TRUE if the query is for a IDropTarget::DragEnter or IDropTarget::DragOver FALSE if the query is for IDropTarget::Drop.

grfKeyState

Key state as defined by OLE.

pdwEffect

Pointer to the variable that contains the effect normally used by a rich edit control. On return, the variable is set to the effect to use.

Return Value

No return value.


IRichEditOleCallback::GetInPlaceContext

Provides the application and document level interfaces and information required to support in-place activation.

HRESULT GetInPlaceContext(

LPOLEINPLACEFRAME FAR * lplpFrame,
LPOLEINPLACEUIWINDOW FAR * lplpDoc,
LPOLEINPLACEFRAMEINFO lpFrameInfo
);
Parameters

lplpframe

Pointer to the pointer variable that receives the address of the IOleInPlaceFrame interface that represents the frame window of the a rich edit control client. Use the AddRef method to increment the reference count the rich edit control releases the interface when it no longer needed.

lplpDoc

Pointer to the pointer variable that receives the address of the IOleInPlaceUIWindow interface that represents the document window of the rich edit control client. An interface need not be returned if the frame and document windows are the same. Use the AddRef method to increment the reference count the rich edit control releases the interface when it no longer needed.

lpFrameInfo

Pointer to the OLEINPLACEFRAMEINFO structure that receives the accelerator information.

Return Value

Returns success status.


IRichEditOleCallback::GetNewStorage

Provides storage for a new object pasted from the clipboard or read in from an RTF stream.

HRESULT GetNewStorage(

LPSTORAGE FAR * lplpstg
);
Parameter

lplpstg

Address to the pointer variable that receives the address of the IStorage interface created for the new object.

Return Value

Returns success status.

This method must be implemented to allow cut/copy/paste and drag and drop of OLE objects.


IRichEditOleCallback::QueryAcceptData

Called on a paste or drag to determine if the data pasted/dragged should be accepted.

HRESULT QueryAcceptData(

LPDATAOBJECT lpdataobj,
CLIPFORMAT FAR * lpcfFormat,
DWORD reco,
BOOL fReally,
HGLOBAL hMetaPict
);
Parameters

lpdataobj

Pointer to the DATAOBJECT structure specifying the data object being pasted or dragged.

lpcfFormat

Pointer to the clipboard format that will be used for the paste or drop operation. If the value pointed to by lpcfFormat is zero, the best available format will be used. If the callback changes the value pointed to by lpcfFormat, the rich edit control only uses that format and the operation will fail if the format is not available.

reco

Clipboard operation flag. Can be one of these values.

RECO_DROP	Drop operation (drag and drop).
RECO_PASTE	Paste from the clipboard.
fReally

Non-zero if the paste or drop is actually happening, zero if this is just a query, such as for EM_CANPASTE.

hMetaPict

Handle to a metafile containing the icon view of an object if DVASPECT_ICON is being imposed on a object by Paste Special.

Return Value

Returns success status. If the SCODE of the result is a failure SCODE, the rich edit control refuses the data and terminates the operation. If the SCODE of the result is S_OK, the control checks the data itself for acceptable formats. A return of a successful SCODE other than S_OK means that the callback either checked the data itself (if fReally is FALSE) or imported the data itself (if fReally is TRUE).

If the application returns a successful result other than S_OK, a rich edit control will not check the read-only state of the edit control.


IRichEditOleCallback::QueryInsertObject

Queries the application as to whether an object should be inserted. This member is called when pasting and when reading RTF.

HRESULT QueryInsertObject(

LPCLSID lpclsid,
LPSTORAGE lpstg,
LONG cp
);
Parameters

lpclsid

Class identifier of the object to be inserted.

lpstg

Storage containing the object.

cp

Character position at which the object will be inserted.

Return Value

Returns success status. If the SCODE of the result is not S_OK, the object is not inserted.


IRichEditOleCallback::ShowContainerUI

Tells the application whether to display its container user interface. The rich edit control looks ahead for doubleclicks and defers the call if appropriate (as described in the OLE documentation). Applications may defer hiding adornments until an IOleInPlaceFrame::SetBorderSpace call is received.

HRESULT ShowContainerUI(

BOOL fShow
);
Parameters

fShow

Show container UI flag. TRUE to show, FALSE otherwise.

Return Value

Returns success status.

This function is called by the OnUIActivate and OnUIDeActivate methods of the IOleInPlaceSite interface.


Animate_Create  (preliminaryWindows NT)
Animate_Create  [image]  (preliminary−Windows NT)

The Animate_Create macro creates an animation control. Animate_Create calls the CreateWindow function.

HWND Animate_Create(

HWND  hwndP,
UINT  id,
DWORD  dwStyle,
HINSTANCE  hInstance
);
Parameters

hwndP

Handle to the parent window.

id

Child window identifier of the animation control.

dwStyle

Window styles.

hInstance

Handle to the instance of the module that is creating the animation control.

Return Value

Returns the handle to the animation control.

Remarks

The Animate_Create macro sets the width and height of the animation control to zero if the ACS_CENTER style is specified. If the ACS_CENTER style is not specified, Animate_Create sets the width and height based on the dimensions of a frame in the AVI clip.

See Also

CreateWindow


CMYK  (preliminaryWindows 95)
CMYK  [image]  (preliminary−Windows 95)

The CMYK macro creates a CMYK color value by combining the specified cyan, magenta, yellow, and black values.

COLORREF CMYK(

c,
m,
y,
k
);
See Also

GetCValue, GetMValue, GetKValue, GetYValue


FORWARD_WM_NOTIFY  (preliminaryWindows NT)
FORWARD_WM_NOTIFY  [image]  (preliminary−Windows NT)

The FORWARD_WM_NOTIFY macro sends or posts the WM_NOTIFY message.

VOID FORWARD_WM_NOTIFY(

hwnd,
idFrom,
pnmhdr,
fn
);
Parameters

hwnd

Handle to the window that receives the WM_NOTIFY message.

idFrom

Identifier of the control sending the message.

pnmhdr

Pointer to an NMHDR structure that contains the notification code and additional information. For some notification messages, this parameter points to a larger structure that has the NMHDR structure as its first member.

fn

Function that sends or posts the WM_NOTIFY message. This parameter can be either the SendMessage or PostMessage function.

Return Value

Returns a value whose meaning depends on the fn parameter.

Remarks

The FORWARD_WM_NOTIFY macro is defined as follows:

#define FORWARD_WM_NOTIFY(hwnd, idFrom, pnmhdr, fn) \

    (void)(fn)((hwnd), WM_NOTIFY, (WPARAM)(int)(id), \

    (LPARAM)(NMHDR FAR*)(pnmhdr))

See Also

NMHDR, PostMessage, SendMessage, WM_NOTIFY


GetBValue

The GetBValue macro retrieves an intensity value for the blue component of a 32-bit red, green, blue (RGB) value.

BYTE GetBValue(

WORD  rgb	// 32-bit RGB value
);
Parameters

rgb

Specifies an RGB color value.

Return Value

The return value is the intensity of the blue component of the specified RGB color.

Remarks

The intensity value is in the range 0 through 255.

The GetBValue macro is defined as follows:

#define GetBValue(rgb)   ((BYTE) ((rgb) >> 16))

See Also

GetGValue, GetRValue, PALETTEINDEX, PALETTERGB, RGB


GetCValue  (preliminaryWindows 95)
GetCValue  [image]  (preliminary−Windows 95)

The GetCValue macro retrieves the cyan color value from a CMYK color value.

BYTE GetCValue(

cmyk
);
See Also

CMYK, GetKValue, GetMValue, GetYValue


GetGValue

The GetGValue macro retrieves an intensity value for the green component of a 32-bit red, green, blue (RGB) value.

BYTE GetGValue(

DWORD  rgb	// 32-bit RGB value
);
Parameters

rgb

Specifies an RGB color value.

Return Value

The return value is the intensity of the green component of the specified RGB color.

Remarks

The intensity value is in the range 0 through 255.

The GetGValue macro is defined as follows:

#define GetGValue(rgb)   ((BYTE) (((WORD) (rgb)) >> 8))

See Also

GetBValue, GetRValue, PALETTEINDEX, PALETTERGB, RGB


GetKValue  (preliminaryWindows 95)
GetKValue  [image]  (preliminary−Windows 95)

The GetKValue macro retrieves the black color value from a CMYK color value.

BYTE GetKValue(

cmyk
);
See Also

CMYK, GetCValue, GetMValue, GetYValue


GetMValue  (preliminaryWindows 95)
GetMValue  [image]  (preliminary−Windows 95)

The GetMValue macro retrieves the magenta color value from a CMYK color value.

BYTE GetMValue(

cmyk
);
See Also

CMYK, GetCValue, GetKValue, GetYValue


GetRValue

The GetRValue macro retrieves an intensity value for the red component of a 32-bit red, green, blue (RGB) value.

BYTE GetRValue(

DWORD  rgb	// 32-bit RGB value
);
Parameters

rgb

Specifies an RGB color value.

Return Value

The return value is the intensity of the red component of the specified RGB color.

Remarks

The intensity value is in the range 0 through 255.

The GetRValue macro is defined as follows:

#define GetRValue(rgb)   ((BYTE) (rgb))

See Also

GetBValue, GetGValue, PALETTEINDEX, PALETTERGB, RGB


GetYValue  (preliminaryWindows 95)
GetYValue  [image]  (preliminary−Windows 95)

The GetYValue macro retrieves the yellow color value from a CMYK color value.

BYTE GetYValue(

cmyk
);
See Also

CMYK, GetCValue, GetMValue, GetKValue,


HANDLE_WM_NOTIFY  (preliminaryWindows NT)
HANDLE_WM_NOTIFY  [image]  (preliminary−Windows NT)

The HANDLE_WM_NOTIFY macro calls a function that processes the WM_NOTIFY message.

HANDLE_WM_NOTIFY(

hwnd,
wParam,
lParam,
fn
);
Parameters

hwnd

Handle to the window that received WM_NOTIFY.

wParam

First parameter of WM_NOTIFY.

lParam

Second parameter of WM_NOTIFY.

fn

Function that is to process WM_NOTIFY.

Return Value

Returns a value whose meaning depends on the fn parameter.

Remarks

The HANDLE_WM_NOTIFY macro is defined as follows:

#define HANDLE_WM_NOTIFY(hwnd, wParam, lParam, fn) \

    (fn)((hwnd), (int)(wParam), (NMHDR FAR*)(lParam))

See Also

WM_NOTIFY


HIBYTE

The HIBYTE macro retrieves the high-order byte from the given 16-bit value.

BYTE HIBYTE(

WORD  wValue	// value from which high-order byte is retrieved
);
Parameters

wValue

Specifies the value to be converted.

Return Value

The return value is the high-order byte of the specified value.

Remarks

The HIBYTE macro is defined as follows:

#define HIBYTE(w)   ((BYTE) (((WORD) (w) >> 8) & 0xFF))

See Also

HIWORD, LOBYTE


HIWORD

The HIWORD macro retrieves the high-order word from the given 32-bit value.

WORD HIWORD(

DWORD  dwValue	// value from which high-order word is retrieved
);
Parameters

dwValue

Specifies the value to be converted.

Return Value

The return value is the high-order word of the specified value.

Remarks

The HIWORD macro is defined as follows:

#define HIWORD(l)   ((WORD) (((DWORD) (l) >> 16) & 0xFFFF))

See Also

HIBYTE, LOWORD


INDEXTOOVERLAYMASK  (preliminaryWindows NT)
INDEXTOOVERLAYMASK  [image]  (preliminary−Windows NT)

The INDEXTOOVERLAYMASK macro prepares the index of an overlay mask so that the ImageList_Draw function can use it.

UINT INDEXTOOVERLAYMASK(

UINT  iOverlay	//
);
Parameters

iOverlay

Index of an overlay mask.

Remarks

The INDEXTOOVERLAYMASK macro is defined as follows:

#define INDEXTOOVERLAYMASK(i) ((i) << 8)


INDEXTOSTATEIMAGEMASK  (preliminaryWindows NT)
INDEXTOSTATEIMAGEMASK  [image]  (preliminary−Windows NT)

The INDEXTOSTATEIMAGEMASK macro prepares the index of a state image so that a tree-view control or list-view control can use the index to retrieve the state image for an item.

UINT INDEXTOSTATEIMAGEMASK(

UINT  i
);
Parameters

i

Index of a state image.

Remarks

The INDEXTOSTATEIMAGEMASK macro is defined as follows:

#define INDEXTOSTATEIMAGEMASK(i) ((i) << 12)


LANGIDFROMLCID

The LANGIDFROMLCID macro retrieves a language identifier from a locale identifier.

WORD LANGIDFROMLCID(

LCID  lcid	// locale identifier
);
Parameters

lcid

Specifies the locale identifier. This parameter may have been created by using the MAKELCID macro.

Return Value

The return value is a language identifier.

Remarks

The LANGIDFROMLCID macro is defined as follows:

#define LANGIDFROMLCID(lcid)   ((WORD) (lcid))

See Also

MAKELANGID, MAKELCID, PRIMARYLANGID, SUBLANGID


LOBYTE

The LOBYTE macro retrieves the low-order byte from the given 16-bit value.

BYTE LOBYTE(

WORD  wValue	// value from which low-order byte is retrieved
);
Parameters

wValue

Specifies the value to be converted.

Return Value

The return value is the low-order byte of the specified value.

Remarks

The LOBYTE macro is defined as follows:

#define LOBYTE(w)   ((BYTE) (w))

See Also

HIBYTE, LOWORD


LOWORD

The LOWORD macro retrieves the low-order word from the given 32-bit value.

WORD LOWORD(

DWORD  dwValue	// value from which low-order word is retrieved
);
Parameters

dwValue

Specifies the value to be converted.

Return Value

The return value is the low-order word of the specified value.

Remarks

The LOWORD macro is defined as follows:

#define LOWORD(l)   ((WORD) (l))

See Also

HIWORD, LOBYTE


MAKEINTATOM

The MAKEINTATOM macro creates an integer atom that represents a character string of decimal digits.

Integer atoms created by this macro can be added to an atom table by using the AddAtom or GlobalAddAtom function.

LPTSTR MAKEINTATOM(

WORD  wInteger	// integer to make into atom
);
Parameters

wInteger

Specifies the numeric value to be made into an integer atom.

Return Value

The return value is a pointer to the atom created for the given integer.

Remarks

Although the return value of the MAKEINTATOM macro is cast as an LPTSTR value, it cannot be used as a string pointer except when it is passed to atom-management functions that require an LPTSTR argument.

The DeleteAtom and GlobalDeleteAtom functions always succeed for integer atoms, even though they do nothing. The string returned by the GetAtomName and GlobalGetAtomName functions for an integer atom is a null-terminated string in which the first character is a pound sign (#) and the remaining characters are the decimal digits used in the MAKEINTATOM macro.

The MAKEINTATOM macro is defined as follows:

#define MAKEINTATOM(i)   (LPTSTR) ((DWORD) ((WORD) (i)))

See Also

AddAtom, DeleteAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalGetAtomName


MAKEINTRESOURCE

The MAKEINTRESOURCE macro converts an integer value to a resource type compatible with Win32 resource-management functions. This macro is used in place of a string containing the name of the resource.

LPTSTR MAKEINTRESOURCE(

WORD  wInteger	// integer to convert
);
Parameters

wInteger

Specifies the integer value to be converted.

Return Value

The return value is the specified value in the low-order word and zero in the high-order word.

Remarks

The return value should be passed only to the Win32 resource-management functions, as the lpType parameter.

The MAKEINTRESOURCE macro is defined as follows:

#define MAKEINTRESOURCE(i)  (LPTSTR) ((DWORD) ((WORD) (i)))


MAKELANGID

The MAKELANGID macro creates a language identifier from a primary language identifier and a sublanguage identifier.

WORD MAKELANGID(

USHORT  usPrimaryLanguage,	// primary language identifier
USHORT  usSubLanguage	// sublanguage identifier
);
Parameters

usPrimaryLanguage

Specifies the primary language identifier. This parameter can be one of the following values:

LANG_BULGARIAN	LANG_JAPANESE
LANG_CHINESE	LANG_KOREAN
LANG_CROATIAN	LANG_NEUTRAL
LANG_CZECH	LANG_NORWEGIAN
LANG_DANISH	LANG_POLISH
LANG_DUTCH	LANG_PORTUGUESE
LANG_ENGLISH	LANG_ROMANIAN
LANG_FINNISH	LANG_RUSSIAN
LANG_FRENCH	LANG_SLOVAK
LANG_GERMAN	LANG_SLOVENIAN
LANG_GREEK	LANG_SPANISH
LANG_HUNGARIAN	LANG_SWEDISH
LANG_ICELANDIC	LANG_TURKISH
LANG_ITALIAN
Windows 95: In addition to the preceding, Windows 95 also defines the following values:

LANG_AFRIKAANS	LANG_HEBREW
LANG_ALBANIAN	LANG_INDONESIAN
LANG_ARABIC	LANG_LATVIAN
LANG_BASQUE	LANG_LITHUANIAN
LANG_BYELORUSSIAN	LANG_SORBIAN
LANG_CATALAN	LANG_THAI
LANG_ESTONIAN	LANG_UKRANIAN
For a user-defined language, usPrimaryLanguage can be a value in the range 0x0200 to 0x03FF. All other values are reserved for system use.

usSubLanguage

Specifies the sublanguage identifier. This parameter can be one of the following values:

SUBLANG_CHINESE_SIMPLIFIED	SUBLANG_FRENCH_SWISS
SUBLANG_CHINESE_TRADITIONAL	SUBLANG_GERMAN
SUBLANG_CHINESE_HONGKONG	SUBLANG_GERMAN_AUSTRIAN
SUBLANG_CHINESE_SINGAPORE	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_SPANISH
SUBLANG_ENGLISH_US	SUBLANG_SPANISH_MEXICAN
SUBLANG_FRENCH	SUBLANG_SPANISH_MODERN
SUBLANG_FRENCH_BELGIAN	SUBLANG_SYS_DEFAULT
SUBLANG_FRENCH_CANADIAN
For a user-defined sublanguage, usSubLanguage can be a value in the range 0x20 to 0x3F. All other values are reserved for system use.

Return Value

The return value is a language identifier that can be used with the FindResourceEx and EnumResLangProc functions.

Remarks

The following three combinations of usPrimaryLanguage and usSubLanguage have special meaning:

Primary language ID	Sublanguage ID	Meaning
LANG_NEUTRAL	SUBLANG_NEUTRAL	Language neutral
LANG_NEUTRAL	SUBLANG_DEFAULT	User default language
LANG_NEUTRAL	SUBLANG_SYS_DEFAULT	System default language
The MAKELANGID macro is defined as follows:

#define MAKELANGID(p, s) ((((WORD) (s)) << 10) | (WORD) (p))

See Also

EnumResLangProc, FindResourceEx, LANGIDFROMLCID, MAKELCID, PRIMARYLANGID, SUBLANGID


MAKELCID

The MAKELCID macro creates a locale identifier from a language identifier.

DWORD MAKELCID(

WORD  wLanguageID,	// language identifier
WORD  wSortID	// sorting identifier
);
Parameters

wLanguageID

Specifies the language identifier. This parameter is a combination of a primary language identifier and a sublanguage identifier and is usually created by using the MAKELANGID macro.

wSortID

Specifies the sort identifier. Use the value SORT_DEFAULT for this parameter.

Return Value

The return value is a locale identifier.

Remarks

The MAKELCID macro is defined as follows:

#define MAKELCID(lgid, srtid)  \

    ((DWORD)((((DWORD)((WORD  )(srtid))) << 16) |  \

            ((DWORD)((WORD  )(lgid)))))

See Also

LANGIDFROMLCID, MAKELANGID, SORTIDFROMLCID


MAKELONG

The MAKELONG macro creates an unsigned 32-bit value by concatenating two given 16-bit values.

DWORD MAKELONG(

WORD  wLow,	// low-order word of long value
WORD  wHigh	// high-order word of long value
);
Parameters

wLow

Specifies the low-order word of the new long value.

wHigh

Specifies the high-order word of the new long value.

Return Value

The return value is an unsigned 32-bit value.

Remarks

The MAKELONG macro is defined as follows:

#define MAKELONG(a, b) \

    ((LONG) (((WORD) (a)) | ((DWORD) ((WORD) (b))) << 16))


MAKELPARAM

The MAKELPARAM macro creates an unsigned 32-bit value for use as an lParam parameter in a message. The macro concatenates two given 16-bit values.

LPARAM MAKELPARAM(

WORD  wLow,	// low-order word
WORD  wHigh	// high-order word
);
Parameters

wLow

Specifies the low-order word of the new long value.

wHigh

Specifies the high-order word of the new long value.

Return Value

The return value is an unsigned 32-bit value.

Remarks

The MAKELPARAM macro is defined as follows:

#define MAKELPARAM(l, h)   ((LPARAM) MAKELONG(l, h))

See Also

MAKELONG, MAKELRESULT, MAKEWPARAM


MAKELRESULT

The MAKELRESULT macro creates an unsigned 32-bit value for use as a return value from a window procedure. The macro concatenates two given 16-bit values.

LRESULT MAKELRESULT(

WORD  wLow,	// low-order word
WORD  wHigh	// high-order word
);
Parameters

wLow

Specifies the low-order word of the new long value.

wHigh

Specifies the high-order word of the new long value.

Return Value

The return value is an unsigned 32-bit value.

Remarks

The MAKELRESULT macro is defined as follows:

#define MAKELRESULT(l, h)   ((LRESULT) MAKELONG(l, h))

See Also

MAKELONG, MAKELPARAM, MAKEWPARAM


MAKEPOINTS

The MAKEPOINTS macro converts a value that contains the x- and y-coordinates of a point into a POINTS structure.

POINTS MAKEPOINTS(

DWORD  dwValue	// coordinates of a point
);
Parameters

dwValue

Specifies the coordinates of a point. The x-coordinate is in the low-order word, and the y-coordinate is in the high-order word.

Return Value

The return value is a pointer to a POINTS structure.

Remarks

The MAKEPOINTS macro is defined as follows:

#define MAKEPOINTS(l)   (*((POINTS FAR *) & (l)))

See Also

GetMessagePos


MAKEROP4

The MAKEROP4 macro creates a quaternary raster operation code for use with the MaskBlt function. The macro takes two ternary raster operation codes as input, one for the foreground and one for the background, and packs their Boolean operation indexes into the high-order word of a 32-bit value. The low-order word of this value will be ignored.

DWORD MAKEROP4(

DWORD  fore,	// foreground ternary raster operation code
DWORD  back	// background ternary raster operation code
);
Parameters

fore

Specifies a foreground ternary raster operation code.

back

Specifies a background ternary raster operation code

Return Value

The return value is a DWORD quaternary raster operation code for use with the MaskBlt function.

Remarks

The MAKEROP4 macro is defined as follows:

#define MAKEROP4(fore,back)

          (DWORD)((((back) << 8) & 0xFF000000) | (fore))

See Also

MaskBlt


MAKEWORD

The MAKEWORD macro creates an unsigned 16-bit integer by concatenating two given unsigned character values.

WORD MAKEWORD(

BYTE  bLow,	// low-order byte of short value
BYTE  bHigh	// high-order byte of short value
);
Parameters

bLow

Specifies the low-order byte of the new short value.

bHigh

Specifies the high-order byte of the new short value.

Return Value

The return value is an unsigned 16-bit integer value.

Remarks

The MAKEWORD macro is defined as follows:

#define MAKEWORD(a, b) \

    ((WORD) (((BYTE) (a)) | ((WORD) ((BYTE) (b))) << 8))


MAKEWPARAM

The MAKEWPARAM macro creates an unsigned 32-bit value for use as a wParam parameter in a message. The macro concatenates two given 16-bit values.

LPARAM MAKEWPARAM(

WORD  wLow,	// low-order word
WORD  wHigh	// high-order word
);
Parameters

wLow

Specifies the low-order word of the new long value.

wHigh

Specifies the high-order word of the new long value.

Return Value

The return value is an unsigned 32-bit value.

Remarks

The MAKEWPARAM macro is defined as follows:

#define MAKEWPARAM(l, h)   ((LPARAM) MAKELONG(l, h))

See Also

MAKELONG, MAKELPARAM, MAKELRESULT


max

The max macro compares two values and returns the larger one. The data type can be any numeric data type, signed or unsigned. The data type of the arguments and the return value is the same.

max(

value1,	// low-order word
value2	// high-order word
);
Parameters

value1

Specifies the first of two values.

value2

Specifies the second of two values.

Return Value

The return value is the greater of the two specified values.

Remarks

The max macro is defined as follows:

#define max(a, b)  (((a) > (b)) ? (a) : (b))

See Also

min


min

The min macro compares two values and returns the smaller one. The data type can be any numeric data type, signed or unsigned. The data type of the arguments and the return value is the same.

min(

value1,
value2
);
Parameters

value1

Specifies the first of two values.

value2

Specifies the second of two values.

Return Value

The return value is the smaller of the two specified values.

Remarks

The min macro is defined as follows:

#define min(a, b)  (((a) < (b)) ? (a) : (b))

See Also

max


PALETTEINDEX

The PALETTEINDEX macro accepts an index to a logical-color palette entry and returns a palette-entry specifier consisting of a 32-bit COLORREF value that specifies the color associated with the given index. An application using a logical color palette can pass this specifier, instead of an explicit red, green, blue (RGB) value, to GDI functions that expect a color. This allows the function to use the color in the specified palette entry.

COLORREF PALETTEINDEX(

WORD  wPaletteIndex	// index to palette entry
);
Parameters

wPaletteIndex

Specifies an index to the palette entry containing the color to be used for a graphics operation.

Return Value

The return value is a logical-palette index specifier.

Remarks

The PALETTEINDEX macro is defined as follows:

#define PALETTEINDEX(i) /

    ((COLORREF) (0x01000000 | (DWORD) (WORD) (i)))

See Also

PALETTERGB, RGB


PALETTERGB

The PALETTERGB macro accepts three values that represent the relative intensities of red, green, and blue and returns a palette-relative red, green, blue (RGB) specifier consisting of 2 in the high-order byte and an RGB value in the three low-order bytes. An application using a color palette can pass this specifier, instead of an explicit RGB value, to functions that expect a color.

COLORREF PALETTERGB(

BYTE  bRed,	// red component of palette-relative RGB
BYTE  bGreen,	// green component of palette-relative RGB
BYTE  bBlue	// blue component of palette-relative RGB
);
Parameters

bRed

Specifies the intensity of the red color field.

bGreen

Specifies the intensity of the green color field.

bBlue

Specifies the intensity of the blue color field.

Return Value

The return value is a palette-relative RGB specifier. For output devices that support logical palettes, Windows matches a palette-relative RGB value to the nearest color in the logical palette of the device context as though the application had specified an index to that palette entry. If an output device does not support a system palette, Windows uses the palette-relative RGB as though it were a conventional RGB doubleword returned by the RGB macro.

Remarks

The PALETTERGB macro is defined as follows:

#define PALETTERGB(r, g, b)  (0x02000000 | RGB(r, g, b))

See Also

PALETTEINDEX, RGB


POINTSTOPOINT

The POINTSTOPOINT macro copies the contents of a POINTS structure into a POINT structure.

POINTSTOPOINT(

POINT  pt,	// POINT structure
POINTS  pts	// POINTS structure
);
Parameters

pt

Specifies the POINT structure to receive the contents of the POINTS structure.

pts

Specifies the POINTS structure to copy.

Remarks

The POINTSTOPOINT macro is defined as follows:

#define POINTSTOPOINT(pt, pts) {(pt).x = (SHORT) LOWORD(pts); \

                               (pt).y = (SHORT) HIWORD(pts);}

See Also

MAKEPOINTS, POINTTOPOINTS


POINTTOPOINTS

The POINTTOPOINTS macro converts a POINT structure to a POINTS structure.

POINTS POINTTOPOINTS(

POINT  pt	// coordinates of a point
);
Parameters

pt

Specifies the POINT structure to convert.

Return Value

The return value is a POINTS structure.

Remarks

The POINTTOPOINTS macro is defined as follows:

#define POINTTOPOINTS(pt) \

    (MAKELONG((short) ((pt).x), (short) ((pt).y)))

See Also

MAKEPOINTS, POINTSTOPOINT


PRIMARYLANGID

The PRIMARYLANGID macro extracts a primary language identifier from a language identifier.

WORD PRIMARYLANGID(

WORD  lgid	// language identifier
);
Parameters

lgid

Specifies the language identifier. This value is a combination of a primary language identifier and a sublanguage identifier and is usually created by using the MAKELANGID macro.

Return Value

The return value is a primary language identifier. The following primary language identifiers are defined:

LANG_BULGARIAN	LANG_JAPANESE
LANG_CHINESE	LANG_KOREAN
LANG_CROATIAN	LANG_NEUTRAL
LANG_CZECH	LANG_NORWEGIAN
LANG_DANISH	LANG_POLISH
LANG_DUTCH	LANG_PORTUGUESE
LANG_ENGLISH	LANG_ROMANIAN
LANG_FINNISH	LANG_RUSSIAN
LANG_FRENCH	LANG_SLOVAK
LANG_GERMAN	LANG_SLOVENIAN
LANG_GREEK	LANG_SPANISH
LANG_HUNGARIAN	LANG_SWEDISH
LANG_ICELANDIC	LANG_TURKISH
LANG_ITALIAN
Remarks

The PRIMARYLANGID macro is defined as follows:

#define PRIMARYLANGID(lgid)    ((WORD  )(lgid) & 0x3ff)

See Also

LANGIDFROMLCID, MAKELANGID, SUBLANGID


RGB

The RGB macro selects a red, green, blue (RGB) color based on the arguments supplied and the color capabilities of the output device.

COLORREF RGB(

BYTE  bRed,	// red component of color
BYTE  bGreen,	// green component of color
BYTE  bBlue	// blue component of color
);
Parameters

cRed

Specifies the intensity of the red color.

cGreen

Specifies the intensity of the green color.

cBlue

Specifies the intensity of the blue color.

Return Value

The return value is the resultant RGB color.

Remarks

The intensity for each argument is in the range 0 through 255. If all three intensities are zero, the result is black. If all three intensities are 255, the result is white.

For information about using color values in a color palette, see the descriptions of the PALETTEINDEX and PALETTERGB macros.

The RGB macro is defined as follows:

#define RGB(r, g ,b)  ((DWORD) (((BYTE) (r) | \

    ((WORD) (g) << 8)) | \

    (((DWORD) (BYTE) (b)) << 16)))

See Also

PALETTEINDEX, PALETTERGB


SORTIDFROMLCID

The SORTIDFROMLCID macro retrieves a sort identifier from a locale identifier.

WORD SORTIDFROMLCID(

LCID  lcid	// locale identifier
);
Parameters

lcid

Specifies the locale identifier. This parameter may have been created by using the MAKELCID macro.

Return Value

The return value is a sort identifier.

Remarks

The SORTIDFROMLCID macro is defined as follows:

#define SORTIDFROMLCID(lcid) \

          ((WORD  )((((DWORD)(lcid)) & NLS_VALID_LOCALE_MASK) >> 16))

The following sort identifiers are defined:

Value	Meaning
SORT_DEFAULT	Specifies the default sort.
SORT_JAPANESE_XJIS	Specifies Japanese XJIS order.
SORT_JAPANESE_UNICODE	Specifies Japanese Unicode order.
SORT_CHINESE_BIG5	Specifies Chinese BIG5 order.
SORT_CHINESE_UNICODE	Specifies Chinese Unicode order.
SORT_KOREAN_KSC	Specifies Korean KSC order.
SORT_KOREAN_UNICODE	Specifies Korean Unicode order.
See Also

MAKELANGID, MAKELCID, PRIMARYLANGID, SUBLANGID


SUBLANGID

The SUBLANGID macro extracts a sublanguage identifier from a language identifier.

WORD SUBLANGID(

WORD  lgid	// language identifier
);
Parameters

lgid

Specifies the language identifier. This value is a combination of a primary language identifier and a sublanguage identifier and is usually created by using the MAKELANGID macro.

Return Value

The return value is a sublanguage identifier. The following sublanguage identifiers are defined:

SUBLANG_CHINESE_HONGKONG	SUBLANG_FRENCH_SWISS
SUBLANG_CHINESE_SIMPLIFIED	SUBLANG_GERMAN
SUBLANG_CHINESE_SINGAPORE	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_SPANISH
SUBLANG_ENGLISH_US	SUBLANG_SPANISH_MEXICAN
SUBLANG_FRENCH	SUBLANG_SPANISH_MODERN
SUBLANG_FRENCH_BELGIAN	SUBLANG_SYS_DEFAULT
SUBLANG_FRENCH_CANADIAN
Remarks

The SUBLANGID macro is defined as follows:

#define SUBLANGID(lgid)        ((WORD  )(lgid) >> 10)

See Also

LANGIDFROMLCID, MAKELANGID, PRIMARYLANGID


TEXT Macro
TEXT

The TEXT macro identifies a string as Unicode when the UNICODE compile flag is used or as an ANSI string when Unicode is not defined.

TEXT(

LPTSTR  string	// address of ANSI or Unicode string
);
Parameters

string

Specifies the string to be interpreted as either Unicode or ANSI.

Remarks

The TEXT macro is defined as follows:

#define TEXT(quote) L##quote


ABM_ACTIVATE

SHAppBarMessage(ABM_ACTIVATE, pabd);

Notifies the system that an appbar has been activated. An appbar should call this message in response to the WM_ACTIVATE message.

Parameter

pabd

Pointer to an APPBARDATA structure that identifies the appbar to activate. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Value

Always returns TRUE.

Remarks

This message is ignored if the hWnd member of the structure pointed to by pabd identifies an autohide appbar. The system automatically sets the Z order for an autohide appbar.

See Also

APPBARDATA


ABM_GETAUTOHIDEBAR

hwndAutoHide = (HWND) SHAppBarMessage(ABM_GETAUTOHIDEBAR, pabd);

Retrieves the handle of the autohide appbar associated with an edge of the screen.

Parameter

pabd

Pointer to an APPBARDATA structure that specifies the screen edge. You must specify the cbSize, hWnd, and uEdge members when sending this message; all other members are ignored.

Return Value

Returns the handle of the autohide appbar. The return value is NULL if an error occurs or if no autohide appbar is associated with the given edge.

See Also

APPBARDATA


ABM_GETSTATE

fuState = (UINT) SHAppBarMessage(ABM_GETSTATE, pabd);

Retrieves the autohide and always-on-top states of the Windows taskbar.

Parameter

pabd

Pointer to an APPBARDATA structure. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Value

Returns zero if the taskbar is not in the autohide or always-on-top state. Otherwise, the return value is one or both of the following values:

ABS_ALWAYSONTOP	The taskbar is in the always-on-top state.
ABS_AUTOHIDE	The taskbar is in the autohide state.
See Also

APPBARDATA


ABM_GETTASKBARPOS

fResult = (BOOL) SHAppBarMessage(ABM_GETTASKBARPOS, pabd);

Retrieves the bounding rectangle of the Windows taskbar.

Parameter

pabd

Pointer to an APPBARDATA structure whose rc member receives the bounding rectangle, in screen coordinates, of the taskbar. You must specify the cbSize and hWnd when sending this message; all other members are ignored.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

APPBARDATA


ABM_NEW

fRegistered = (BOOL) SHAppBarMessage(ABM_NEW, pabd);

Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar. An appbar should send this message before sending any other appbar messages.

Parameter

pabd

Pointer to an APPBARDATA structure that contains the new appbar's window handle and message identifier. You must specify the cbSize, hWnd, and uCallbackMessage members when sending this message; all other members are ignored.

Return Value

Returns TRUE if successful or FALSE if an error occurs or the appbar is already registered.

See Also

APPBARDATA


ABM_QUERYPOS

SHAppBarMessage(ABM_QUERYPOS, pabd);

Requests a size and screen position for an appbar. The message proposes a screen edge and a bounding rectangle for the appbar. The system adjusts the bounding rectangle so that the appbar does not interfere with the Windows taskbar or any other appbars. An appbar should send this message before sending the ABM_SETPOS message.

Parameter

pabd

Pointer to an APPBARDATA structure. The uEdge member specifies a screen edge, and the rc member contains the proposed bounding rectangle. When the SHAppBarMessage function returns, rc contains the approved bounding rectangle. You must specify the cbSize, hWnd, uEdge, and rc members when sending this message; all other members are ignored.

Return Value

Always returns TRUE.

See Also

APPBARDATA


ABM_REMOVE

SHAppBarMessage(ABM_REMOVE, pabd);

Unregisters an appbar, removing it from the system's internal list. The system no longer sends notification messages to the appbar nor prevents other applications from using the screen area occupied by the appbar.

Parameter

pabd

Pointer to an APPBARDATA structure that contains the handle of the appbar to unregister. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Value

Always returns TRUE.

This message causes the system to send the ABN_POSCHANGED notification message to all appbars.

See Also

APPBARDATA


ABM_SETAUTOHIDEBAR

fSussess = (BOOL) SHAppBarMessage(ABM_SETAUTOHIDEBAR, pabd);

Registers or unregisters an autohide appbar for an edge of the screen. The system allows only one autohide appbar for each edge on a first come, first served basis.

Parameter

pabd

Pointer to an APPBARDATA structure. The uEdge member specifies the screen edge. The lParam parameter is set to TRUE to register the appbar or FALSE to unregister it. You must specify the cbSize, hWnd, uEdge, and lParam members when sending this message; all other members are ignored.

Return Value

Returns TRUE if successful or FALSE if an error occurs or an autohide appbar is already registered for the given edge.

See Also

APPBARDATA


ABM_SETPOS

SHAppBarMessage(ABM_SETPOS, pabd);

Sets the size and screen position of an appbar. The message specifies a screen edge to and the bounding rectangle for the appbar. The system may adjust the bounding rectangle so that the appbar does not interfere with the Windows taskbar or any other appbars.

Parameters

pabd

Pointer to an APPBARDATA structure. The uEdge member specifies a screen edge, and the rc member contains the bounding rectangle. When the SHAppBarMessage function returns, rc contains the approved bounding rectangle. You must specify the cbSize, hWnd, uEdge, and rc members when sending this message; all other members are ignored.

Return Value

Always returns TRUE.

This message causes the system to send the ABN_POSCHANGED notification message to all appbars.

See Also

APPBARDATA


ABM_WINDOWPOSCHANGED

SHAppBarMessage(ABM_WINDOWPOSCHANGED, pabd);

Notifies the system when an appbar's position has changed. An appbar should call this message in response to the WM_WINDOWPOSCHANGED message.

Parameter

pabd

Pointer to an APPBARDATA structure that identifies the appbar to activate. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Value

Always returns TRUE.

Remarks

This message is ignored if the hWnd member of the structure pointed to by pabd identifies an autohide appbar.

See Also

APPBARDATA


ABN_FULLSCREENAPP

ABN_FULLSCREENAPP

fOpen = (BOOL) lParam;

Notifies an appbar when a full-screen application is opening or closing. When a full-screen application is opening, an appbar must drop to the bottom of the Z order. When it is closing, the appbar should restore its Z order position. This notification is sent in the form of an application-defined message that is set by the ABM_NEW message.

Parameter

fOpen

Flag specifying whether a full screen application is opening or closing. This parameter is TRUE if opening or FALSE if closing.

Return Value

No return value.


ABN_POSCHANGED

Notifies an appbar when an event has occurred that may effect the appbar's size and position. Events include changes in the taskbar's size, position, and visibility state, as well as the addition, removal, or resizing of another appbar on the same side of the screen.

Return Value

No return value.

Remarks

An appbar should respond to this notification message by sending the ABM_QUERYPOS and ABM_SETPOS messages. If its position has changed, the appbar should call the MoveWindow function to move itself to the new position.

See Also

MoveWindow


ABN_STATECHANGE

ABN_STATECHANGE

Notifies an appbar that the taskbar's autohide or always-on-top state has changed — that is, the user has checked or unchecked the "Always on top" or "Auto hide" check box on the taskbar's property sheet. An appbar can use this notification message to set its state to conform to that of the taskbar, if desired.

Return Value

No return value.


ABN_WINDOWARRANGE

ABN_WINDOWARRANGE

fBeginning = (BOOL) lParam;

Notifies an appbar that the user has selected the Cascade, Tile Horizontally, or Tile Vertically command from the taskbar's context menu.

Parameter

fBeginning

Flag specifying whether the cascade or tile operation is beginning. This parameter is TRUE if the operation is beginning and the windows have not yet been moved. It is FALSE if the operation has completed.

Return Value

No return value.

Remarks

The system sends this notification message twice — first with lParam set to TRUE and then with lParam set to FALSE. The first notification is sent before the windows are cascaded or tiled, and the second is sent after the cascade or tile operation has occurred.


ACM_OPEN  (preliminaryWindows NT)
ACM_OPEN  (preliminary−Windows NT)

ACM_OPEN

wParam = 0;

lParam = (LPARAM) (LPSTR) lpszName;

// Corresponding macro

BOOL Animate_Open(hwnd, lpszName);

// Related macro

BOOL Animate_Close(hwnd);

The ACM_OPEN message opens an AVI clip and displays its first frame in an animation control.

Parameters

hwnd

Handle to the animation control.

lpszName

Pointer to a buffer that contains the path of the .AVI file or the name of an AVI resource. Alternatively, this parameter can consist of the AVI resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro. If this parameter is NULL, the system closes the .AVI file that was previously opened for the specified animation control, if any.

The AVI file or resource specified by lpszName must not contain audio. It must be silent.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

You can only open silent AVI clips. AVI files or resources containing audio will not load. ACM_OPEN and Animate_Open fail if lpszSource specifies a non-silent AVI clip.

You can use Animate_Close to close an .AVI file or AVI resource that was previously opened for the specified animation control.

The Animate_Open macro is defined as follows:

#define Animate_Open(hwnd, szName)   \

    (BOOL)SendMessage(hwnd, ACM_OPEN, 0, (LPARAM)(LPTSTR)(szName))

The Animate_Close macro is defined as follows:

#define Animate_Close(hwnd)                 Animate_Open(hwnd, NULL)

The Animate_Close macro always returns FALSE.

See Also

MAKEINTRESOURCE


ACM_PLAY  (preliminaryWindows NT)
ACM_PLAY  (preliminary−Windows NT)

ACM_PLAY

wParam = (WPARAM) (UINT) cRepeat;

lParam = (LPARAM) MAKELONG(wFrom, wTo);

// Corresponding macro

BOOL Animate_Play(hwndAnim, wFrom, wTo, cRepeat);

// Related macro

BOOL Animate_Seek(hwndAnim, wFrame);

The ACM_PLAY message plays an AVI clip in an animation control. The control plays the clip in the background while the thread continues executing.

Parameters

cRepeat

Number of times to replay the AVI clip. A value of  − 1 means replay the clip indefinitely.

hwndAnim

Handle to the animation control in which to play the AVI clip.

wFrom

Zero-based index of the frame where playing begins. The value must be less than 65,536. A value of zero means begin with the first frame in the AVI clip.

wTo

Zero-based index of the frame where playing ends. The value must be less than 65,536. A value of  − 1 means end with the last frame in the AVI clip.

wFrame

Zero-based index of the frame to display.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

You can use Animate_Seek to direct the animation control to display a particular frame of the AVI clip.

The Animate_Play macro is defined as follows:

#define Animate_Play(hwnd, from, to, rep)   \

    (BOOL)SendMessage(hwnd, ACM_PLAY, (WPARAM)(UINT)(rep),  \

        (LPARAM)MAKELONG(from, to))

The Animate_Seek macro is defined as follows:

#define Animate_Seek(hwnd, frame)           Animate_Play(hwnd, frame, frame, 1)


ACM_STOP  (preliminaryWindows NT)
ACM_STOP  (preliminary−Windows NT)

ACM_STOP

wParam = 0;

lParam = 0;

// Corresponding macro

BOOL Animate_Stop(hwnd);

The ACM_STOP message stops playing an AVI clip in an animation control.

Parameters

hwnd

Handle to the animation control.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.


ACN_START  (preliminaryWindows NT)
ACN_START  (preliminary−Windows NT)

ACN_START

The ACN_START notification message notifies an animation control's parent window that the associated AVI clip has started playing. This notification message is sent in the form of a WM_COMMAND message.

Return Value

No return value.

See Also

WM_COMMAND


ACN_STOP  (preliminaryWindows NT)
ACN_STOP  (preliminary−Windows NT)

ACN_STOP

The ACN_STOP notification message notifies an animation control's parent window that the associated AVI clip has stopped playing. This notification message is sent in the form of a WM_COMMAND message.

Return Value

No return value.

See Also

WM_COMMAND


BM_CLICK

BM_CLICK

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

An application sends a BM_CLICK message to simulate the user clicking a button. This message causes the button to receive a WM_LBUTTONDOWN and a WM_LBUTTONUP message, and the button's parent window to receive a BN_CLICKED notification message.

Parameters

This message has no parameters.

Return Value

This message does not return a value.

See Also

BN_CLICKED, WM_LBUTTONDOWN, WM_LBUTTONUP


BM_GETCHECK

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.

Return Value

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 is unchecked. Same as the Windows 95 constant BST_UNCHECKED.
1	Button is checked. Same as the Windows 95 constant BST_CHECKED.
2	Button is grayed, indicating an indeterminate state (applies only if the button has the BS_3STATE or BS_AUTO3STATE style). Same as the Windows 95 constant BST_INDETERMINATE.
BST_CHECKED	Windows 95 only: Button is checked.
BST_INDETERMINATE	Windows 95 only: Button is grayed, indicating an indeterminate state (applies only if the button has the BS_3STATE or BS_AUTO3STATE style).
BST_UNCHECKED	Windows 95 only: Button is unchecked
If the button has any other style, the return value is zero.

See Also

BM_GETSTATE, BM_SETCHECK


BM_GETIMAGE  (preliminaryWindows 95)
BM_GETIMAGE  (preliminary−Windows 95)

BM_GETIMAGE

wParam = 0;     // not used, must be zero

lParam = 0;     // not used, must be zero

An application sends a BM_GETIMAGE message to retrieve the handle of the image (icon or bitmap) associated with the button.

Parameters

This message has no parameters.

Return Value

The return value is the handle of the image, if any; otherwise, it is NULL.

See Also

BM_SETIMAGE


BM_GETSTATE

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.

Return Value

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 zero 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 (applies only if the button has the BS_3STATE or BS_AUTO3STATE style). A three-state check box is grayed when its state is indeterminate.
0x0004	Specifies the highlight state. A nonzero value indicates that the button is highlighted. A button is automatically highlighted when the user positions the cursor over it and presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button. Same as the Windows 95 constant BST_PUSHED.
0x0008	Specifies the focus state. A nonzero value indicates that the button has the keyboard focus. Same as the Windows 95 constant BST_FOCUS.
BST_CHECKED	Windows 95 only: Indicates the button is checked. Same as the Windows NT return value of 1.
BST_FOCUS	Windows 95 only: Indicates the button has the keyboard focus. Same as the Windows NT return value of 0x0008.
BST_INDETERMINATE	Windows 95 only: Indicates the button is grayed because the state of the button is indeterminate. This value applies only if the button has the BS_3STATE or BS_AUTO3STATE style. Same as the Windows NT return value of 2.
BST_PUSHED	Windows 95 only: Indicates the button is highlighted as if the user had pushed it. Same as the Windows NT return value of 0x0004.
BST_UNCHECKED	Windows 95 only: Indicates the button is unchecked. Same as the Windows NT return value of zero.
See Also

BM_GETCHECK, BM_SETSTATE


BM_SETCHECK

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.

Parameters

fCheck

Value of wParam. Specifies the check state. This parameter can be one of the following values:

Value	Meaning
0	Sets the button state to unchecked. Same as the Windows 95 constant BST_UNCHECKED.
1	Sets the button state to checked. Same as the Windows 95 constant BST_CHECKED.
2	Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style. Same as the Windows 95 constant BST_INDETERMINATE.
BST_CHECKED	Windows 95 only: Sets the button state to checked.
BST_INDETERMINATE	Windows 95 only: Sets the button state to grayed, indicating an indeterminate state. Use this value only if the button has the BS_3STATE or BS_AUTO3STATE style.
BST_UNCHECKED	Windows 95 only: Sets the button state to unchecked
Return Value

This message always returns zero.

Remarks

The BM_SETCHECK message has no effect on push buttons.

See Also

BM_GETCHECK, BM_GETSTATE, BM_SETSTATE


BM_SETIMAGE  (preliminaryWindows 95)
BM_SETIMAGE  (preliminary−Windows 95)

BM_SETIMAGE

wParam = 0;                         // not used, must be zero

lParam = (LPARAM) (HANDLE) hImage;  // handle of the image

An application sends a BM_SETIMAGE message to associate a new image (icon or bitmap) with the button.

Parameters

hImage

Value of lParam. Identifies the image to associate with the button.

Return Value

The return value is the handle of the image previously associated with the button, if any; otherwise, it is NULL.

See Also

BM_GETIMAGE


BM_SETSTATE

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. The highlight state indicates whether the button is highlighted as if the user had pushed it.

Parameters

fState

Value of wParam. Specifies whether the button is to be highlighted. A value of TRUE highlights the button. A value of FALSE removes any highlighting.

Return Value

This message always returns zero.

Remarks

Highlighting only affects the appearance of a button. It has no effect on the check state of a radio button or check box.

A button is automatically highlighted when the user positions the cursor over it and presses and holds the left mouse button. The highlighting is removed when the user releases the mouse button.

See Also

BM_GETSTATE, BM_SETCHECK


BM_SETSTYLE

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.

Parameters

dwStyle

Value of wParam. Specifies the button style. For an explanation of button styles, see the following Remarks section.

fRedraw

Value of the low-order word of lParam. Specifies whether the button is to be redrawn. A value of TRUE redraws the button; a value of FALSE does not redraw the button.

Return Value

This message always returns zero.

Remarks

Following are the available button styles:

Style	Meaning
BS_3STATE	Creates a button that is the same as a check box, except that the box can be grayed as well as checked or unchecked. Use the grayed state to show that the state of the check box is not determined.
BS_AUTO3STATE	Creates a button that is the same as a three-state check box, except that the box changes its state when the user selects it. The state cycles through checked, grayed, and unchecked.
BS_AUTOCHECKBOX	Creates a button that is the same as a check box, except that the check state automatically toggles between checked and unchecked each time the user selects the check box.
BS_AUTORADIOBUTTON	Creates a button that is the same as a radio button, except that when the user selects it, Windows automatically sets the button's check state to checked and automatically sets the check state for all other buttons in the same group to unchecked.
BS_CHECKBOX	Creates a small, empty check box with text. By default, the text is displayed to the right of the check box. To display the text to the left of the check box, combine this flag with the BS_LEFTTEXT style (or on Windows 95 only, with the equivalent BS_RIGHTBUTTON style).
BS_DEFPUSHBUTTON	Creates a push button that behaves like a BS_PUSHBUTTON style button, but also has a heavy black border. If the button is in a dialog box, the user can select the button by pressing the ENTER key, even when the button does not have the input focus. This style is useful for enabling the user to quickly select the most likely (default) option.
BS_GROUPBOX	Creates a rectangle in which other controls can be grouped. Any text associated with this style is displayed in the rectangle's upper left corner.
BS_LEFTTEXT	Places text on the left side of the radio button or check box when combined with a radio button or check box style. Same as the Windows 95 BS_RIGHTBUTTON style.
BS_OWNERDRAW	Creates an owner-drawn button. The owner window receives a WM_MEASUREITEM message when the button is created and a WM_DRAWITEM message when a visual aspect of the button has changed. Do not combine the BS_OWNERDRAW style with any other button styles.
BS_PUSHBUTTON	Creates a push button that posts a WM_COMMAND message to the owner window when the user selects the button.
BS_RADIOBUTTON	Creates a small circle with text. By default, the text is displayed to the right of the circle. To display the text to the left of the circle, combine this flag with the BS_LEFTTEXT style (or on Windows 95 only, with the equivalent BS_RIGHTBUTTON style). Use radio buttons for groups of related, but mutually exclusive choices.
BS_USERBUTTON	Obsolete, but provided for compatibility with 16-bit versions of Windows. Win32-based applications should use BS_OWNERDRAW instead.
BS_BITMAP	Windows 95 only: Specifies that the button displays a bitmap.
BS_BOTTOM	Windows 95 only: Places text at the bottom of the button rectangle.
BS_CENTER	Windows 95 only: Centers text horizontally in the button rectangle.
BS_ICON	Windows 95 only: Specifies that the button displays an icon.
BS_LEFT	Windows 95 only: Left-justifies the text in the button rectangle. However, if the button is a check box or radio button that does not have the BS_RIGHTBUTTON style, the text is left justified on the right side of the check box or radio button.
BS_MULTILINE	Windows 95 only: Wraps the button text to multiple lines if the text string is too long to fit on a single line in the button rectangle.
BS_NOTIFY	Windows 95 only: Sends the parent window notification messages in addition to BN_CLICKED and BN_DBLCLK, which a button sends regardless of whether it has this style.
BS_PUSHLIKE	Windows 95 only: Makes a button (such as a check box, three-state check box, or radio button) look and act like a push button. The button looks raised when it isn't pushed or checked, and sunken when it is pushed or checked.
BS_RIGHT	Windows 95 only: Right-justifies text in the button rectangle. However, if the button is a check box or radio button that does not have the BS_RIGHTBUTTON style, the text is right justified on the right side of the check box or radio button.
BS_RIGHTBUTTON	Windows 95 only: Positions a radio button's circle or a check box's square on the right side of the button rectangle. Same as the BS_LEFTTEXT style.
BS_TEXT	Windows 95 only: Specifies that the button displays text.
BS_TOP	Windows 95 only: Places text at the top of the button rectangle.
BS_VCENTER	Windows 95 only: Places text in the middle (vertically) of the button rectangle.
See Also

WM_COMMAND, WM_DRAWITEM, WM_MEASUREITEM


BN_CLICKED

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.

Remarks

A disabled button does not send a BN_CLICKED notification message to its parent window.

See Also

WM_COMMAND


BN_DBLCLK  (preliminaryWindows 95)
BN_DBLCLK  [image]  (preliminary−Windows 95)

BN_DBLCLK

idButton = (int) LOWORD(wParam);    // identifier of button

hwndButton = (HWND) lParam;         // handle of button

The BN_DBLCLK notification message is sent when the user double-clicks a button that has the BS_OWNERDRAW or BS_RADIOBUTTON style. The parent window of the button receives this notification message through a WM_COMMAND message.

BN_DBLCLK is the same as the BN_DOUBLECLICKED notification message.

This notification is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

BN_CLICKED, BN_DOUBLECLICKED, WM_COMMAND


BN_DISABLE

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 message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

Windows 95 only: Only buttons that have the BS_NOTIFY style send the BN_DISABLE notification message.

See Also

DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_DOUBLECLICKED

BN_DOUBLECLICKED

The BN_DOUBLECLICKED notification message is sent when the user double-clicks a button that has the BS_OWNERDRAW or BS_RADIOBUTTON style. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_DOUBLECLICKED is the same as the Windows 95 BN_DBLCLK notification message.

This notification is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

BN_DBLCLK, DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_HILITE

BN_HILITE

The BN_HILITE notification message is sent when the user selects a button. The parent window of the button receives this notification message through the WM_COMMAND message. This notification message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

BN_HILITE is the same as the Windows 95 BN_PUSHED notification message.

Windows 95 only: Only buttons that have the BS_NOTIFY style send the BN_HILITE notification message.

See Also

BN_PUSHED, BN_UNHILITE, DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_KILLFOCUS  (preliminaryWindows 95)
BN_KILLFOCUS  (preliminary−Windows 95)

BN_KILLFOCUS

The BN_KILLFOCUS notification message is sent when a button loses the keyboard focus. The button must have the BS_NOTIFY style to send this notification message. The parent window of the button receives this notification message through the WM_COMMAND message.

See Also

BN_SETFOCUS, WM_COMMAND


BN_PAINT

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 message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

Windows 95 only: Only buttons that have the BS_NOTIFY style send the BN_PAINT notification message.

See Also

DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_PUSHED  (preliminaryWindows 95)
BN_PUSHED  [image]  (preliminary−Windows 95)

BN_PUSHED

The BN_PUSHED notification message is sent when the push state of a button is set to pushed. The button must have the BS_NOTIFY style to send this notification message. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_PUSHED is the same as the BN_HILITE notification message.

This notification message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

BN_HILITE, BN_UNPUSHED, DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_SETFOCUS  (preliminaryWindows 95)
BN_SETFOCUS  (preliminary−Windows 95)

BN_SETFOCUS

The BN_SETFOCUS notification message is sent when a button receives the keyboard focus. The button must have the BS_NOTIFY style to send this notification message. The parent window of the button receives this notification message through the WM_COMMAND message.

See Also

BN_KILLFOCUS, WM_COMMAND


BN_UNHILITE

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.

BN_UNHILITE is the same as the Windows 95 BN_UNPUSHED notification message.

This notification message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

Windows 95 only: Only buttons that have the BS_NOTIFY style send the BN_UNHILITE notification message.

See Also

BN_HILITE, BN_UNPUSHED, DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


BN_UNPUSHED  (preliminaryWindows 95)
BN_UNPUSHED  [image]  (preliminary−Windows 95)

BN_PUSHED

The BN_UNPUSHED notification message is sent when the push state of a button is set to unpushed. The button must have the BS_NOTIFY style to send this notification message. The parent window of the button receives this notification message through the WM_COMMAND message.

BN_UNPUSHED is the same as the BN_UNHILITE notification message.

This notification message is provided for compatibility with applications written for versions of Windows earlier than version 3.0. New applications should use the BS_OWNERDRAW button style and the DRAWITEMSTRUCT structure for this task.

See Also

BN_PUSHED, DRAWITEMSTRUCT, WM_COMMAND, WM_DRAWITEM


CB_ADDSTRING

CB_ADDSTRING

wParam = 0;                         // not used; must be zero

lParam = (LPARAM) (LPCTSTR) 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.

Parameters

lpsz

Value of lParam. Points to the null-terminated string to be added. If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the value of the lpsz parameter is stored as item data rather than the string it would otherwise point to. The item data can be retrieved or modified by sending the CB_GETITEMDATA or CB_SETITEMDATA message.

Return Value

The return value is the zero-based index to the string in the list box of the combo box. If an error occurs, the return value is CB_ERR. If insufficient space is available to store the new string, it is CB_ERRSPACE.

Remarks

If you create an owner-drawn combo box with the CBS_SORT style but without the CBS_HASSTRINGS style, the WM_COMPAREITEM message is sent one or more times to the owner of the combo box so the new item can be properly placed in the list.

To insert a string at a specific location within the list, use the CB_INSERTSTRING message.

See Also

CB_DIR, CB_INSERTSTRING, WM_COMPAREITEM


CB_DELETESTRING

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the string to delete.

Return Value

The return value is a count of the strings remaining in the list. If the index parameter specifies an index greater than the number of items in the list, the return value is CB_ERR.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, Windows sends a WM_DELETEITEM message to the owner of the combo box so the application can free any additional data associated with the item.

See Also

CB_RESETCONTENT, WM_DELETEITEM


CB_DIR

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 filenames to the list box of a combo box.

Parameters

uAttrs

Value of wParam. Specifies the attributes of the files to be added to the list box. It can be any combination of the following values:

Value	Meaning
DDL_ARCHIVE	Includes archived files.
DDL_DIRECTORY	Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).
DDL_DRIVES	Includes drives. Drives are listed in the form [-x-], where x is the drive letter.
DDL_EXCLUSIVE	Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.
DDL_HIDDEN	Includes hidden files.
DDL_READONLY	Includes read-only files.
DDL_READWRITE	Includes read-write files with no additional attributes.
DDL_SYSTEM	Includes system files.
lpszFileSpec

Value of lParam. Points to the null-terminated string that specifies the filename to add to the list. If the filename contains any wildcards (for example, *.*), all files that match and have the attributes specified by the uAttrs parameter are added to the list.

Return Value

The return value is the zero-based index of the last filename added to the list. If an error occurs, the return value is CB_ERR. If insufficient space is available to store the new strings, it is CB_ERRSPACE.

See Also

CB_ADDSTRING, CB_INSERTSTRING, DlgDirList, DlgDirListComboBox


CB_FINDSTRING

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.

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item preceding the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is −1, the entire list box is searched from the beginning.

lpszFind

Value of lParam. Points to the null-terminated string that contains the prefix to search for. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Value

The return value is the zero-based index of the matching item. If the search is unsuccessful, it is CB_ERR.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, what the CB_FINDSTRING message does depends on whether your application uses the CBS_SORT style. If you use the CBS_SORT style, WM_COMPAREITEM messages are sent to the owner of the combo box to determine which item matches the specified string. If you do not use the CBS_SORT style, the CB_FINDSTRING message searches for a list item that matches the value of the lpszFind parameter.

See Also

CB_FINDSTRINGEXACT, CB_SELECTSTRING, CB_SETCURSEL, WM_COMPAREITEM


CB_FINDSTRINGEXACT

CB_FINDSTRINGEXACT

wParam = (WPARAM) indexStart;      // item before start of search

lParam = (LPARAM)(LPCSTR)lpszFind; // address of string to search for

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.

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item preceding the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is −1, the entire list box is searched from the beginning.

lpszFind

Value of lParam. Points to the null-terminated string to search for. This string can contain a complete filename, including the extension. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Value

The return value is the zero-based index of the matching item. If the search is unsuccessful, it is CB_ERR.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, what the CB_FINDSTRINGEXACT message does depends on whether your application uses the CBS_SORT style. If you use the CBS_SORT style, WM_COMPAREITEM messages are sent to the owner of the combo box to determine which item matches the specified string. If you do not use the CBS_SORT style, the CB_FINDSTRINGEXACT message searches for a list item that matches the value of the lpszFind parameter.

See Also

CB_FINDSTRING, CB_SELECTSTRING, WM_COMPAREITEM


CB_GETCOUNT

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.

Return Value

The return value is the number of items in the list box. If an error occurs, it is CB_ERR.

Remarks

The index is zero-based, so the returned count is one greater than the index value of the last item.


CB_GETCURSEL

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.

Return Value

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

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.

Parameters

lprc

Value of lParam. Points to the RECT structure that is to receive the coordinates.

Return Value

This message always returns CB_OKAY.

See Also

RECT


CB_GETDROPPEDSTATE

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.

Return Value

If the list box is visible, the return value is TRUE; otherwise, it is FALSE.

See Also

CB_SHOWDROPDOWN


CB_GETDROPPEDWIDTH  (preliminaryWindows 95)
CB_GETDROPPEDWIDTH  [image]  (preliminary−Windows 95)

CB_GETDROPPEDWIDTH

wParam = 0;     // not used, must be zero

lParam = 0;     // not used, must be zero

An application sends the CB_GETDROPPEDWIDTH message to retrieve the minimum allowable width, in pixels, of the list box of a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

Parameters

This message has no parameters.

Return Value

If the message succeeds, the return value is the width, in pixels.

If the message fails, the return value is CB_ERR.

Remarks

By default, the minimum allowable width of the drop-down list box is 0. The width of the list box is either the minimum allowable width or the combo box width, whichever is larger.

See Also

CB_SETDROPPEDWIDTH


CB_GETEDITSEL

CB_GETEDITSEL

wParam = (WPARAM) (LPDWORD) lpdwStart; // receives starting position

lParam = (LPARAM) (LPDWORD) lpdwEnd;   // receives ending position

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.

Parameters

lpdwStart

Value of wParam. Points to a 32-bit value that receives the starting position of the selection. This parameter can be set to NULL.

lpdwEnd

Value of lParam. Points to a 32-bit value that receives the ending position of the selection. This parameter can be set to NULL.

Return Value

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

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.

Return Value

If the combo box has the extended user interface, the return value is TRUE; otherwise, it is FALSE.

Remarks

By default, the F4 key opens or closes the list and the DOWN ARROW changes the current selection. In a combo box with the extended user interface, the F4 key is disabled and pressing the DOWN ARROW key opens the drop-down list.

See Also

CB_SETEXTENDEDUI


CB_GETHORIZONTALEXTENT  (preliminaryWindows 95)
CB_GETHORIZONTALEXTENT  [image]  (preliminary−Windows 95)

CB_GETHORIZONTALEXTENT

wParam = 0;     // not used, must be zero

lParam = 0;     // not used, must be zero

An application sends the CB_GETHORIZONTALEXTENT message to retrieve from a combo box the width, in pixels, by which the list box can be scrolled horizontally (the scrollable width). This is applicable only if the list box has a horizontal scroll bar.

Parameters

This message has no parameters.

Return Value

The return value is the scrollable width, in pixels.

See Also

CB_SETHORIZONTALEXTENT


CB_GETITEMDATA

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the item.

Return Value

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

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.

Parameters

index

Value of wParam. Specifies the combo box component whose height is to be retrieved.

This parameter must be −1 to retrieve the height of the selection field. It must be zero to retrieve the height of list items, unless the combo box has the CBS_OWNERDRAWVARIABLE style. In that case, the index parameter is the zero-based index of a specific list item.

Return Value

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

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the string to retrieve.

lpszBuffer

Value of lParam. Points to the buffer that receives the string. The buffer must have sufficient space for the string and a terminating null character. You can send a CB_GETLBTEXTLEN message prior to the CB_GETLBTEXT message to retrieve the length, in bytes, of the string.

Return Value

The return value is the length of the string, in bytes, excluding the terminating null character. If the index parameter does not specify a valid index, the return value is CB_ERR.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the buffer pointed to by the lpszBuffer parameter of the message receives the 32-bit value associated with the item (the item data).

See Also

CB_GETLBTEXTLEN


CB_GETLBTEXTLEN

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the string.

Return Value

The return value is the length of the string, in characters, excluding the terminating null character. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

If the index parameter does not specify a valid index, the return value is CB_ERR.

Remarks

Under certain conditions, the return value is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the operating system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; so you can always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

CB_GETLBTEXT, GetWindowText, LB_GETTEXT, WM_GETTEXT


CB_GETLOCALE

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.

Return Value

The return value is a 32-bit value that specifies the current locale of the combo box. The high word contains the country code and the low-order word contains the language identifier.

Remarks

The language identifier is made up of a sublanguage identifier and a primary language identifier. The PRIMARYLANGID macro obtains the primary language identifier and the SUBLANGID macro obtains the sublanguage identifier.

See Also

CB_ADDSTRING, CB_SETLOCALE, PRIMARYLANGID, SUBLANGID


CB_GETTOPINDEX  (preliminaryWindows 95)
CB_GETTOPINDEX  [image]  (preliminary−Windows 95)

CB_GETTOPINDEX

wParam = 0;     // not used, must be zero

lParam = 0;     // not used, must be zero

An application sends the CB_GETTOPINDEX message to retrieve the zero-based index of the first visible item in the list box portion of a combo box. Initially the item with index 0 is at the top of the list box, but if the list box contents have been scrolled, another item may be at the top.

Parameters

This message has no parameters.

Return Value

If the message is successful, the return value is the index of the first visible item in the list box of the combo box.

If the message fails, the return value is CB_ERR.

See Also

CB_SETTOPINDEX


CB_INITSTORAGE  (preliminaryWindows 95)
CB_INITSTORAGE  [image]  (preliminary−Windows 95)

CB_INITSTORAGE

wParam = (WPARAM) (int) cItems;     // number of items to add

lParam = (LPARAM) (DWORD) cb;       // amount of memory to allocate, in bytes

An application sends the CB_INITSTORAGE message before adding a large number of items to the list box portion of a combo box. This message allocates memory for storing list box items.

Parameters

cItems

Specifies the number of items to add.

cb

Specifies the amount of memory to allocate for item strings, in bytes.

Return Value

If the message is successful, the return value is the maximum number of items that the memory object can store.

If the message fails, the return value is CB_ERR.

Remarks

This message helps speed up the initialization of combo boxes that have a large number of items (over 100). It preallocates the specified amount of memory so that subsequent CB_ADDSTRING, CB_INSERTSTRING and CB_DIR messages take the shortest possible time. You can use estimates for the cItems and cb parameters. If you overestimate, some extra memory is allocated, if you underestimate, the normal allocation is used for items that exceed the preallocated amount.

See Also

CB_ADDSTRING, CB_DIR, CB_INSERTSTRING


CB_INSERTSTRING

CB_INSERTSTRING

wParam = (WPARAM) index;         // item index

lParam = (LPARAM) (LPCTSTR) 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.

Parameters

index

Value of wParam. Specifies the zero-based index of the position at which to insert the string. If this parameter is −1, the string is added to the end of the list.

lpsz

Value of lParam. Points to the null-terminated string to be inserted. If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the value of the lpsz parameter is stored rather than the string it would otherwise point to.

Return Value

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

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.

Parameters

cchLimit

Value of wParam. Specifies the maximum number of characters the user can enter. If this parameter is zero, the text length is set to 0x7FFFFFFE characters.

Return Value

The return value is always TRUE.

Remarks

If the combo box does not have the CBS_AUTOHSCROLL style, setting the text limit to be larger than the size of the edit control has no effect.

The CB_LIMITTEXT message limits only the text the user can enter. It has no effect on any text already in the edit control when the message is sent, nor does it affect the length of the text copied to the edit control when a string in the list box is selected.

The default limit to the text a user can enter in the edit control is 30,000 characters.


CB_RESETCONTENT

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.

Return Value

This message always returns CB_OKAY.

Remarks

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, the owner of the combo box receives a WM_DELETEITEM message for each item in the combo box.

See Also

CB_DELETESTRING, WM_DELETEITEM


CB_SELECTSTRING

CB_SELECTSTRING

wParam = (WPARAM) indexStart;          // item before first selection

lParam = (LPARAM) (LPCSTR) lpszSelect; // address 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.

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item preceding the first item to be searched. When the search reaches the bottom of the list, it continues from the top of the list back to the item specified by the indexStart parameter. If indexStart is −1, the entire list is searched from the beginning.

lpszSelect

Value of lParam. Points to the null-terminated string that contains the prefix to search for. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Value

If the string is found, the return value is the index of the selected item. If the search is unsuccessful, the return value is CB_ERR and the current selection is not changed.

Remarks

A string is selected only if the characters from the starting point match the characters in the prefix string.

If you create the combo box with an owner-drawn style but without the CBS_HASSTRINGS style, what the CB_SELECTSTRING message does depends on whether you use the CBS_SORT style. If the CBS_SORT style is used, the system sends WM_COMPAREITEM messages to the owner of the combo box to determine which item matches the specified string. If you do not use the CBS_SORT style, CB_SELECTSTRING attempts to match the DWORD value against the value of the lpszSelect parameter.

See Also

CB_FINDSTRING, CB_FINDSTRINGEXACT, CB_SETCURSEL, WM_COMPAREITEM


CB_SETCURSEL

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the string to select. If the index parameter is −1, any current selection in the list is removed and the edit control is cleared.

Return Value

If the message is successful, the return value is the index of the item selected. If index is greater than the number of items in the list or if index is set to −1, the return value is CB_ERR and the selection is cleared.

See Also

CB_FINDSTRING, CB_GETCURSEL, CB_SELECTSTRING


CB_SETDROPPEDWIDTH  (preliminaryWindows 95)
CB_SETDROPPEDWIDTH  [image]  (preliminary−Windows 95)

CB_SETDROPPEDWIDTH

wParam = (WPARAM) wWidth,     // width of list box, in pixels

lParam = 0,                   // not used, must be zero

An application sends the CB_SETDROPPEDWIDTH message to set the maximum allowable width, in pixels, of the list box of a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

Parameters

wWidth

Specifies the width of the list box, in pixels.

Return Value

If the message is successful, The return value is the new width of the list box.

If the message fails, the return value is CB_ERR.

Remarks

By default, the minimum allowable width of the drop-zdown list box is 0. The width of the list box is either the minimum allowable width or the combo box width, whichever is larger.

See Also

CB_GETDROPPEDWIDTH


CB_SETEDITSEL

CB_SETEDITSEL

wParam = 0;                                // not used; must be zero

lParam = MAKELPARAM((ichStart), (ichEnd);  // start and end position

An application sends a CB_SETEDITSEL message to select characters in the edit control of a combo box.

Parameters

ichStart

Value of the low-order word of lParam; this specifies the starting position. If this parameter is set to −1, the selection, if any, is removed.

ichEnd

Value of the high-order word of lParam; this specifies the ending position. If this parameter is set to −1, all text from the starting position to the last character in the edit control is selected.

Return Value

If the message succeeds, the return value is TRUE. If the message is sent to a combo box with the CBS_DROPDOWNLIST style, it is CB_ERR.

Remarks

The positions are zero-based. The first character of the edit control is in the zero position. The first character after the last selected character is in the ending position. For example, to select the first four characters of the edit control, use a starting position of 0 and an ending position of 4.

See Also

CB_GETEDITSEL


CB_SETEXTENDEDUI

CB_SETEXTENDEDUI

wParam = (WPARAM) (BOOL) fExtended;    // extended user interface 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.

Parameters

fExtended

Value of wParam. Specifies whether the combo box uses the extended user interface or the default user interface. A value of TRUE selects the extended user interface; a value of FALSE selects the standard user interface.

Return Value

If the operation succeeds, the return value is CB_OKAY. If an error occurs, it is CB_ERR.

Remarks

By default, the F4 key opens or closes the list and the DOWN ARROW changes the current selection. In the extended user interface, the F4 key is disabled and the DOWN ARROW key opens the drop-down list.

See Also

CB_GETEXTENDEDUI


CB_SETHORIZONTALEXTENT  (preliminaryWindows 95)
CB_SETHORIZONTALEXTENT  [image]  (preliminary−Windows 95)

CB_SETHORIZONTALEXTENT

wParam = (WPARAM) cxExtent;            // scrollable width of list box, in pixels

lParam = 0;                            // not used, must be zero

An application sends the CB_SETHORIZONTALEXTENT message to set the width, in pixels, by which a list box can be scrolled horizontally (the scrollable width). If the width of the list box is smaller than this value, the horizontal scroll bar horizontally scrolls items in the list box. If the width of the list box is equal to or greater than this value, the horizontal scroll bar is hidden or, if the combo box has the CBS_DISABLENOSCROLL style, disabled.

Parameters

cxExtent

Specifies the scrollable width of the list box, in pixels.

Return Value

No return value.

See Also

CB_GETHORIZONTALEXTENT


CB_SETITEMDATA

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.

Parameters

index

Value of wParam. Specifies the item's zero-based index.

dwData

Value of lParam. Specifies the new value to be associated with the item.

Return Value

If an error occurs, the return value is CB_ERR.

Remarks

If the specified item is in an owner-drawn combo box created without the CBS_HASSTRINGS style, this message replaces the 32-bit value in the lParam parameter of the CB_ADDSTRING or CB_INSERTSTRING message that added the item to the combo box.

See Also

CB_ADDSTRING, CB_GETITEMDATA, CB_INSERTSTRING


CB_SETITEMHEIGHT

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.

Parameters

index

Value of wParam. Specifies the component of the combo box for which to set the height.

This parameter must be −1 to set the height of the selection field. It must be zero to set the height of list items, unless the combo box has the CBS_OWNERDRAWVARIABLE style. In that case, the index parameter is the zero-based index of a specific list item.

height

Value of lParam. Specifies the height, in pixels, of the combo box component identified by index.

Return Value

If the index or height is invalid, the return value is CB_ERR.

Remarks

The selection field height in a combo box is set independently of the height of the list items. An application must ensure that the height of the selection field is not smaller than the height of a particular list item.

See Also

CB_GETITEMHEIGHT, WM_MEASUREITEM


CB_SETLOCALE

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.

Parameters

wLocaleID

Value of wParam. Specifies the locale identifier for the combo box to use for sorting when adding text.

Return Value

The return value is the previous locale identifier. If wParam specifies a locale not installed on the system, the return value is CB_ERR and the current combo box locale is not changed.

Remarks

Use the MAKELCID macro to construct a locale identifier and the MAKELANGID macro to construct a language identifier. The language identifier is made up of a primary language identifier and a sublanguage identifier.

See Also

CB_ADDSTRING, CB_GETLOCALE, MAKELANGID, MAKELCID


CB_SETTOPINDEX  (preliminaryWindows 95)
CB_SETTOPINDEX  [image]  (preliminary−Windows 95)

CB_SETTOPINDEX

wParam = (WPARAM) index;            // zero-based index of item list

lParam = 0;                         // not used, must be zero

An application sends the CB_SETTOPINDEX message to ensure that a particular item is visible in the list box of a combo box. The system scrolls the list box contents so that either the specified item appears at the top of the list box or the maximum scroll range has been reached.

Parameters

index

Specifies the zero-based index of the list item.

Return Value

If the message is successful, the return value is zero.

If the message fails, the return value is CB_ERR.

See Also

CB_GETTOPINDEX


CB_SHOWDROPDOWN

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.

Parameters

fShow

Value of wParam. Specifies whether the drop-down list box is to be shown or hidden. A value of TRUE shows the list box; a value of FALSE hides it.

Return Value

The return value is always TRUE.

Remarks

This message has no effect on a combo box created with the CBS_SIMPLE style.

See Also

CB_GETDROPPEDSTATE


CBN_CLOSEUP

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.

Remarks

This notification message is not sent to a combo box that has the CBS_SIMPLE style.

In general, you cannot predict the order in which notifications will be sent. In particular, a CBN_SELCHANGE notification message may occur either before or after a CBN_CLOSEUP notification message.

See Also

CBN_DROPDOWN, CBN_SELCHANGE, WM_COMMAND


CBN_DBLCLK

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.

Remarks

This notification message occurs only for a combo box with the CBS_SIMPLE style. In a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style, a double-click cannot occur because a single click closes the list box.

See Also

CBN_SELCHANGE, WM_COMMAND


CBN_DROPDOWN

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.

Remarks

This notification message can occur only for a combo box with the CBS_DROPDOWN or CBS_DROPDOWNLIST style.

See Also

CBN_CLOSEUP, WM_COMMAND


CBN_EDITCHANGE

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.

Remarks

If the combo box has the CBS_DROPDOWNLIST style, this notification message does not occur.

See Also

CBN_EDITUPDATE, WM_COMMAND


CBN_EDITUPDATE

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 message is sent after the control has formatted the text, but before it displays the text. The parent window of the combo box receives this notification message through the WM_COMMAND message.

Remarks

If the combo box has the CBS_DROPDOWNLIST style, this notification message does not occur.

See Also

CBN_EDITCHANGE, WM_COMMAND


CBN_ERRSPACE

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

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

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

CBN_SELENDCANCEL

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

The CBN_SELENDCANCEL notification message is sent when the user selects an item, but then selects another control or closes the dialog box. It indicates the user's initial selection is to be ignored. The parent window of the combo box receives this notification message through the WM_COMMAND message.

Remarks

In a combo box with the CBS_SIMPLE style, the CBN_SELENDCANCEL notification message is not sent. The CBN_SELENDOK notification message is sent immediately before every CBN_SELCHANGE notification message.

If the WS_EX_NOPARENTNOTIFY extended window style is specified for the combo box, the CBN_SELENDCANCEL notification message is not sent.

See Also

CBN_SELCHANGE, CBN_SELENDOK, WM_COMMAND


CBN_SELENDOK

CBN_SELENDOK

idComboBox = (int) LOWORD(wParam);  // identifier of combo box

hwndComboBox = (HWND) lParam;       // handle of combo box

The CBN_SELENDOK notification message is sent when the user selects a list item, or selects an item and then closes the list. It indicates that the user's selection is to be processed. The parent window of the combo box receives this notification message through the WM_COMMAND message.

Remarks

In a combo box with the CBS_SIMPLE style, the CBN_SELENDOK notification message is sent immediately before every CBN_SELCHANGE notification message.

If the WS_EX_NOPARENTNOTIFY extended window style is specified for the combo box, the CBN_SELENDOK notification message is not sent.

See Also

CBN_SELCHANGE, CBN_SELENDCANCEL, WM_COMMAND


CBN_SETFOCUS

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

CPL_DBLCLK

uAppNum = (UINT) lParam1;   // application number

lData = (LONG) lParam2;     // application-defined value

The CPL_DBLCLK message is sent to a Control Panel application when the user double-clicks the icon of a dialog box supported by the application.

Parameters

uAppNum

Value of lParam1. Specifies the dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT − 1).

lData

Value of lParam2. Specifies the value that the Control Panel application loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the dialog box. The application loads lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Return Value

If a Control Panel application processes this message successfully, the return value is zero; otherwise, it is nonzero.

Remarks

In response to this message, a Control Panel application must display the corresponding dialog box.

See Also

CPL_GETCOUNT, CPL_INQUIRE, CPL_NEWINQUIRE, CPL_SELECT, CPLINFO, NEWCPLINFO


CPL_EXIT

CPL_EXIT

The CPL_EXIT message is sent once to a Control Panel application before the controlling application releases the DLL containing the application.

Parameters

This function has no parameters.

Return Value

If a Control Panel application processes this message successfully, it should return zero.

Remarks

This message is sent after the last CPL_STOP message is sent.

In response to this message, a Control Panel application must free any memory that it has allocated and perform global-level cleanup.

See Also

CPL_STOP, FreeLibrary


CPL_GETCOUNT

CPL_GETCOUNT

The CPL_GETCOUNT message is sent to a Control Panel application to retrieve the number of dialog boxes supported by the application.

Parameters

This function has no parameters.

Return Value

A Control Panel application should return the number of dialog boxes it supports.

Remarks

This message is sent immediately after the CPL_INIT message.

See Also

CPL_INIT


CPL_INIT

CPL_INIT

The CPL_INIT message is sent to a Control Panel application to prompt it to perform global initialization, especially memory allocation.

Parameters

This function has no parameters.

Return Value

If initialization succeeds, a Control Panel application should return nonzero. Otherwise, it should return zero. If the application returns zero, the controlling application ends communication and releases the DLL containing the Control Panel application.

Remarks

Because this is the only way a Control Panel application can signal an error condition, the application should allocate memory in response to this message.

This message is sent immediately after the DLL containing the application is loaded.

See Also

FreeLibrary


CPL_INQUIRE

CPL_INQUIRE

uAppNum = (UINT) lParam1;     // application number

lpcpli = (LPCPLINFO) lParam2; // structure for application info.

The CPL_INQUIRE message is sent to a Control Panel application to request information about a dialog box that the application supports.

This message has been superseded by the CPL_NEWINQUIRE message. The CPL_INQUIRE message is provided for compatibility with Windows versions 3.0 and earlier. Win32-based applications should use CPL_NEWINQUIRE.

Parameters

uAppNum

Value of lParam1. Specifies the dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT − 1).

lpcpli

Value of lParam2. Points to a CPLINFO structure. The application must fill this structure with resource identifiers for the icon, short name, description, and any user-defined value associated with the dialog box.

Return Value

If a Control Panel application processes this message successfully, it should return zero.

Remarks

This message is sent once for each dialog box supported by the Control Panel application. It is sent immediately after the CPL_GETCOUNT message. The application can perform initialization for the dialog box when it receives this message. If the application must allocate memory, it should do so in response to the CPL_INIT message.

See Also

CPL_GETCOUNT, CPL_INIT, CPL_NEWINQUIRE, CPLINFO


CPL_NEWINQUIRE

CPL_NEWINQUIRE

uAppNum = (UINT) lParam1;         // application number

lpncpli = (LPNEWCPLINFO) lParam2; // structure for appl. info.

The CPL_NEWINQUIRE message is sent to a Control Panel application to request information about a dialog box that the application supports.

Parameters

uAppNum

Value of lParam1. Specifies the dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT − 1).

lpncpli

Value of lParam2. Specifies the address of a NEWCPLINFO structure. The Control Panel application should fill this structure with information about the dialog box.

Return Value

If a Control Panel application processes this message successfully, it should return zero.

Remarks

This message is sent once for each dialog box supported by the application. It is sent immediately after the CPL_GETCOUNT message. Upon receiving this message, the application can initialize the dialog box. If the application must allocate memory, it should do so in response to the CPL_INIT message.

See Also

CPL_GETCOUNT, CPL_INIT, CPL_INQUIRE, NEWCPLINFO


CPL_SELECT

CPL_SELECT

uAppNum = (UINT) lParam1;   // application number

lData = (LONG) lParam2;     // application-defined value

The CPL_SELECT message is sent to a Control Panel application when the user selects the icon of a dialog box supported by the application.

Parameters

uAppNum

Value of lParam1. Specifies the dialog box number.

lData

Value of lParam2. Specifies the value that the Control Panel application loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the dialog box. The application loads the lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Return Value

If a Control Panel application processes this message successfully, it should return zero.

See Also

CPL_DBLCLK, CPL_INQUIRE, CPL_NEWINQUIRE, CPLINFO, NEWCPLINFO


CPL_STOP

CPL_STOP

uAppNum = (UINT) lParam1;   // application number

lData = (LONG) lParam2;     // application-defined value

The CPL_STOP message is sent once for each dialog box when the application controlling the Control Panel application closes.

Parameters

uAppNum

Value of lParam1. Specifies the dialog box number.

lData

Value of lParam2. Specifies the value that the Control Panel application loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the dialog box. The application loads lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Return Value

If a Control Panel application processes this message successfully, it should return zero.

Remarks

In response to this message, a Control Panel application must perform cleanup for the given dialog box.

See Also

CPL_EXIT, CPL_GETCOUNT, CPL_INQUIRE, CPL_NEWINQUIRE, CPLINFO, NEWCPLINFO


DBT_CONFIGCHANGED  (preliminaryWindows 95)
DBT_CONFIGCHANGED  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The DBT_CONFIGCHANGED device message indicates that the current configuration has changed, due to a dock or undock. An application or driver that stores data in the registry under the HKEY_CURRENT_CONFIG key should update the data.

Parameters

dwData

Pointer to a DEV_BROADCAST_HDR structure identifying the device.

Return Value

Return TRUE.

See Also

DEV_BROADCAST_HDR


DBT_DEVICEARRIVAL  (preliminaryWindows 95)
DBT_DEVICEARRIVAL  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The DBT_DEVICEARRIVAL device message is sent when a device has been inserted and is now available.

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device inserted.

Return Value

Return TRUE.

See Also

DEV_BROADCAST_HDR


DBT_DEVICEQUERYREMOVE  (preliminaryWindows 95)
DBT_DEVICEQUERYREMOVE  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The DBT_DEVICEQUERYREMOVE device message is sent to request permission to remove a device. Any application can deny this request and cancel the removal.

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device to remove.

Return Value

Return TRUE to grant permission, FALSE otherwise.

See Also

DEV_BROADCAST_HDR


DBT_DEVICEQUERYREMOVEFAILED  (preliminaryWindows 95)
DBT_DEVICEQUERYREMOVEFAILED  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The DBT_DEVICEQUERYREMOVEFAILED device message is sent when a request to remove a device has been canceled.

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device.

Return Value

Return TRUE.

See Also

DEV_BROADCAST_HDR


DBT_DEVICEREMOVECOMPLETE  (preliminaryWindows 95)
DBT_DEVICEREMOVECOMPLETE  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The DBT_DEVICEREMOVECOMPLETE device message is sent when a device has been removed.

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device removed.

Return Value

Return TRUE.

Remarks

The operating system may send a DBT_DEVICEREMOVECOMPLETE message without sending corresponding DBT_DEVICEQUERYREMOVE and DBT_DEVICEREMOVEPENDING messages. In such cases, the applications and drivers must recover from the loss of the device the best they can.

See Also

DBT_DEVICEQUERYREMOVE, DBT_DEVICEREMOVEPENDING, DEV_BROADCAST_HDR


DBT_DEVICEREMOVEPENDING  (preliminaryWindows 95)
DBT_DEVICEREMOVEPENDING  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The DBT_DEVICEREMOVEPENDING device message is sent when the device is about to be removed. This message is the last chance for applications and drivers to prepare for the removal of the device.

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device to remove.

Return Value

Return TRUE.

See Also

DEV_BROADCAST_HDR


DBT_DEVICETYPESPECIFIC  (preliminaryWindows 95)
DBT_DEVICETYPESPECIFIC  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The DBT_DEVICETYPESPECIFIC device message is sent when a device-specific event occurs.

Parameters

dwData

Address of a DEV_BROADCAST_HDR structure identifying the device.

Return Value

Return TRUE.

See Also

DEV_BROADCAST_HDR


DBT_DEVNODES_CHANGED

Applications should not process the DBT_DEVNODES_CHANGED message. This message may not be available on all operating systems.


DBT_USERDEFINED

dwData = (DWORD) lParam;

The DBT_USERDEFINED device message identifies a user-defined system message. DBT_USERDEFINED is sent as the wParam parameter of the WM_DEVICECHANGE message.

dwData

Address of the user-defined data. The data must be in the format specified by the _DEV_BROADCAST_USERDEFINED structure.

See Also

_DEV_BROADCAST_USERDEFINED, WM_DEVICECHANGE


DL_BEGINDRAG  (preliminaryWindows NT)
DL_BEGINDRAG  (preliminary−Windows NT)

DL_BEGINDRAG

idCtl = (int) wParam;

pDragInfo = (LPDRAGLISTINFO) lParam;

The DL_BEGINDRAG notification message notifies the parent window of a drag list box that the user has clicked the left mouse button on a list item. A drag list box sends DL_BEGINDRAG in the form of a drag list message.

Parameters

idCtl

Control identifier of the drag list box.

pDragInfo

Pointer to a DRAGLISTINFO structure that contains the DL_BEGINDRAG notification code, the handle to the drag list box, and the cursor position.

Return Value

The parent window should return TRUE to begin a drag operation or FALSE to prevent a drag operation.

Remarks

When processing this notification message, a window procedure typically determines the list item at the specified cursor position by using the LBItemFromPt function and then returns TRUE or FALSE, depending on whether the item should be dragged. Before returning TRUE, the window procedure should save the index of the list item, so the application knows which item to move or copy when the drag operation is completed.

See Also

DRAGLISTINFO, LBItemFromPt


DL_CANCELDRAG  (preliminaryWindows NT)
DL_CANCELDRAG  (preliminary−Windows NT)

DL_CANCELDRAG

idCtl = (int) wParam;

pDragInfo = (LPDRAGLISTINFO) lParam;

The DL_CANCELDRAG notification message signals that the user has canceled a drag operation by clicking the right mouse button or pressing the ESC key. A drag list box sends DL_CANCELDRAG to its parent window in the form of a drag list message.

Parameters

idCtl

Control identifier of the drag list box.

pDragInfo

Pointer to a DRAGLISTINFO structure that contains the DL_CANCELDRAG notification code, the handle to the drag list box, and the cursor position.

Return Value

No return value.

Remarks

By processing the DL_CANCELDRAG notification message, an application can reset its internal state to indicate that dragging is not in effect.

See Also

DRAGLISTINFO


DL_DRAGGING  (preliminaryWindows NT)
DL_DRAGGING  (preliminary−Windows NT)

DL_DRAGGING

idCtl = (int) wParam;

pDragInfo = (LPDRAGLISTINFO) lParam;

The DL_DRAGGING notification message signals that the user has moved the mouse while dragging an item. DL_DRAGGING is also sent periodically during dragging even if the mouse is not moved. A drag list box sends this notification to its parent window in the form of a drag list message.

Parameters

idCtl

Control identifier of the drag list box.

pDragInfo

Pointer to a DRAGLISTINFO structure that contains the DL_DRAGGING notification code, the handle to the drag list box, and the cursor position.

Return Value

The return value determines the type of mouse cursor that the drag list should set; it can be the DL_STOPCURSOR, DL_COPYCURSOR, or DL_MOVECURSOR value. If any other value is returned, the cursor does not change.

Remarks

A window procedure typically processes the DL_DRAGGING notification message by determining the item under the cursor and then drawing an insert icon. To get the item under the cursor, use the LBItemFromPt function, specifying TRUE for the bAutoScroll parameter. This option causes the drag list box to scroll periodically if the cursor is above or below its client area. To draw the insert icon, use the DrawInsert function.

See Also

DrawInsert, DRAGLISTINFO, LBItemFromPt


DL_DROPPED  (preliminaryWindows NT)
DL_DROPPED  (preliminary−Windows NT)

DL_BEGINDRAG

idCtl = (int) wParam;

pDragInfo = (LPDRAGLISTINFO) lParam;

The DL_DROPPED notification message signals that the user has completed a drag operation by releasing the left mouse button. A drag list box sends DL_DROPPED to its parent window in the form of a drag list message.

Parameters

idCtl

Control identifier of the drag list box.

pDragInfo

Pointer to a DRAGLISTINFO structure that contains the DL_DROPPED notification code, the handle to the drag list box, and the cursor position.

Return Value

No return value.

Remarks

A window procedure typically processes this notification message by inserting or copying the dragged list item before the list item under the cursor. To retrieve the index of the item at the cursor position, use the LBItemFromPoint function. Note that the DL_DROPPED notification message is sent even if the cursor is not on a list item. In that case, LBItemFromPoint returns − 1.

See Also

DRAGLISTINFO


DM_GETDEFID

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.

Return Value

If a default push button exists, the high-order word of the return value contains the value DC_HASDEFID and the low-order word contains the control identifier. Otherwise, the return value is zero.

Remarks

The DefDlgProc function processes this message.

See Also

DefDlgProc, DM_SETDEFID


DM_REPOSITION  (preliminaryWindows 95)
DM_REPOSITION  [image]  (preliminary−Windows 95)

DM_REPOSITION

wParam = 0;

lParam = 0;

The DM_REPOSITION message repositions a top-level dialog box so that it fits within the desktop area. An application can send this message to a dialog box after resizing it to ensure that the entire dialog box remains visible.

Parameters

This message has no parameters.

Return Value

This message has no return value.

Remarks

This message has no effect if the dialog box is a child window.


DM_SETDEFID

DM_SETDEFID

wParam = idControl; // identifier of new default push button

This message has been replaced by EM_SETLIMITTEXT. An application sends a DM_SETDEFID message to change the identifier of the default push button for a dialog box.

Parameters

idControl

Value of wParam. Specifies the identifier of a push button control that will become the default.

Remarks

This message is processed by the DefDlgProc function. To set the default push button, the function can send WM_GETDLGCODE and BM_SETSTYLE messages to the given control and the current default push button.

Using the DM_SETDEFID message can result in more than one button appearing to have the default push button state. When Windows brings up a dialog, it draws the first push button in the dialog template with the default state border. Sending a DM_SETDEFID message to change the default button will not always remove the default state border from the first push button. In these cases, the application should send a BM_SETSTYLE message to change the first push button border style.

Return Value

The return value is always TRUE.

See Also

DefDlgProc, BM_SETSTYLE, DM_GETDEFID, WM_GETDLGCODE


EM_CANPASTE  (preliminaryWindows NT)
EM_CANPASTE  (preliminary−Windows NT)

EM_CANPASTE

wParam = (WPARAM) (UINT) uFormat;

lParam = 0;

The EM_CANPASTE message determines whether a rich edit control can paste a specified clipboard format.

Parameters

uFormat

Value identifying the clipboard format to try, or zero to try any format currently on the clipboard.

Return Value

Returns a nonzero value if the clipboard format can be pasted or zero otherwise.


EM_CANUNDO

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.

Return Value

If the edit control can correctly process the EM_UNDO message, the return value is TRUE; otherwise, it is FALSE.

See Also

EM_UNDO


EM_CHARFROMPOS  (preliminaryWindows 95)
EM_CHARFROMPOS  [image]  (preliminary−Windows 95)

EM_CHARFROMPOS

wParam = 0;

lParam = MAKELPARAM(x, y);

An application sends an EM_CHARFROMPOS message to retrieve the zero-based character index and zero-based line index of the character nearest the specified point in an edit control.

Parameters

x

Value of the low-order word of lParam. Specifies the x-coordinate of a point in the edit control's client area. The coordinate is relative to the upper-left corner of the client area.

y

Value of the high-order word of lParam. Specifies the y-coordinate of a point in the edit control's client area. The coordinate is relative to the upper-left corner of the client area.

Return Value

The return value specifies the character index in the low-order word and the line index in the high-order word. For single-line edit controls, the line index is always 0. The return value is the last character in the edit control if the given point is beyond the last character in the control. The return value is −1 if the specified point is outside the client area of the edit control.

See Also

EM_POSFROMCHAR


EM_DISPLAYBAND  (preliminaryWindows NT)
EM_DISPLAYBAND  (preliminary−Windows NT)

EM_DISPLAYBAND

wParam = 0;

lParam = (LPARAM) (LPRECT) lprc;

The EM_DISPLAYBAND message displays a portion of a rich edit control's contents, as previously formatted for a device using the EM_FORMATRANGE message.

Parameters

lprc

Pointer to a RECT structure specifying the area of the device to display to.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

Text and OLE objects are clipped by the rectangle. The application does not need to set the clipping region.

See Also

EM_FORMATRANGE, RECT


EM_EMPTYUNDOBUFFER

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.

Return Value

This message does not return a value.

Remarks

The undo flag is automatically reset whenever the edit control receives a WM_SETTEXT or EM_SETHANDLE message.

See Also

EM_CANUNDO, EM_SETHANDLE, EM_UNDO, WM_SETTEXT


EM_EXGETSEL  (preliminaryWindows NT)
EM_EXGETSEL  (preliminary−Windows NT)

EM_EXGETSEL

wParam = 0;

lParam = (LPARAM) (CHARRANGE FAR *) lpchr;

The EM_EXGETSEL message retrieves the starting and ending character positions of the selection in a rich edit control.

Parameters

lpchr

Pointer to a CHARRANGE structure that receives the selection range.

Return Value

No return value.

See Also

CHARRANGE


EM_EXLIMITTEXT  (preliminaryWindows NT)
EM_EXLIMITTEXT  (preliminary−Windows NT)

EM_EXGETSEL

wParam = 0;

lParam = (LPARAM) (DWORD) cchTextMax;

The EM_EXLIMITTEXT message sets an upper limit to the amount of text in a rich edit control.

Parameters

cchTextMax

Maximum amount of text or zero for the default maximum. An OLE object counts as a single character. The default maximum is 32K.

Return Value

No return value.


EM_EXLINEFROMCHAR  (preliminaryWindows NT)
EM_EXLINEFROMCHAR  (preliminary−Windows NT)

EM_EXLINEFROMCHAR

wParam = 0;

lParam = (LPARAM) (DWORD) ichCharPos;

The EM_EXLINEFROMCHAR message determines which line contains the specified character in a rich edit control.

Parameters

ichCharPos

Zero-based index of the character.

Return Value

Returns the zero-based index of the line.


EM_EXSETSEL  (preliminaryWindows NT)
EM_EXSETSEL  (preliminary−Windows NT)

EM_EXSETSEL

wParam = 0;

lParam = (LPARAM) (CHARRANGE FAR *) ichCharRange;

The EM_EXSETSEL message selects a range of characters in a rich edit control.

Parameters

ichCharPos

Zero-based index of the character.

Return Value

Returns the zero-based index of the line.


EM_FINDTEXT  (preliminaryWindows NT)
EM_FINDTEXT  (preliminary−Windows NT)

EM_FINDTEXT

wParam = (WPARAM) (UINT) fuFlags;

lParam = (LPARAM) (FINDTEXT FAR *) lpFindText;

The EM_FINDTEXT message finds text within a rich edit control.

Parameters

fuFlags

Zero or more of the FT_MATCHCASE and FT_WHOLEWORD values.

lpFindText

Pointer to a FINDTEXT structure containing information about the find operation.

Return Value

Returns the zero-based character position of the next match, or  − 1 if there are no more matches.

See Also

FINDTEXT


EM_FINDWORDBREAK  (preliminaryWindows NT)
EM_FINDWORDBREAK  (preliminary−Windows NT)

EM_FINDWORDBREAK

wParam = (WPARAM) (UINT) code;

lParam = (LPARAM) (DWORD) ichStart;

The EM_FINDWORDBREAK message finds the next word break before or after the specified character position, or retrieves information about the character at that position.

Parameters

code

Action to take. This parameter can be one of these values:

Value	Meaning
WB_CLASSIFY	Returns the character class and word break flags of the character at the specified position.
WB_ISDELIMITER	Returns TRUE if the character at the specified position is a delimiter, or FALSE otherwise.
WB_LEFT	Finds the nearest character before the specified position that begins a word.
WB_LEFTBREAK	Finds the next word end before the specified position.
WB_MOVEWORDLEFT	Finds the next character that begins a word before the specified position. This value is used during CTRL+LEFT key processing.
WB_MOVEWORDRIGHT	Finds the next character that begins a word after the specified position. This value is used during CTRL+RIGHT key processing.
WB_RIGHT	Finds the next character that begins a word after the specified position.
WB_RIGHTBREAK	Finds the next end-of-word delimiter after the specified position.
ichStart

Zero-based character position to start from.

Return Value

Returns the character index of the word break, unless the code parameter is the WB_CLASSIFY or WB_ISDELIMITER value. For more information, see the description of the code parameter.

Remarks

If code is WB_LEFT and WB_RIGHT, the word break procedure finds word breaks only after delimiters. This matches the functionality of an edit control. If code is WB_MOVEWORDLEFT or WB_MOVEWORDRIGHT, the word break procedure also compares character classes and word break flags.


EM_FMTLINES

EM_FMTLINES

wParam = (WPARAM) (BOOL) fAddEOL;   // linebreak flag

lParam = 0;                         // not used; must be zero

An application sends an EM_FMTLINES message to set the inclusion flag of soft linebreak characters on or off within a multiline edit control. A soft linebreak consists of two carriage returns and a linefeed and is inserted at the end of a line that is broken because of wordwrapping.

Parameters

fAddEOL

Value of wParam. Specifies whether soft-linebreak characters are to be inserted. A value of TRUE inserts the characters; a value of FALSE removes them.

Return Value

The return value is identical to the fAddEOL parameter.

Remarks

This message affects only the buffer returned by the EM_GETHANDLE message and the text returned by the WM_GETTEXT message. It has no effect on the display of the text within the edit control.

The EM_FMTLINES message does not affect a line that ends with a hard linebreak. A hard linebreak consists of one carriage return and a linefeed.

Note that the size of the text changes when this message is processed.

See Also

EM_GETHANDLE, WM_GETTEXT


EM_FORMATRANGE  (preliminaryWindows NT)
EM_FORMATRANGE  (preliminary−Windows NT)

EM_FORMATRANGE

wParam = (WPARAM) (BOOL) fRender;

lParam = (LPARAM) (FORMATRANGE FAR *) lpFmt;

The EM_FORMATRANGE message formats a range of text in a rich edit control for a specific device.

Parameters

fRender

Value specifying whether to render the text. If this parameter is nonzero, the text is rendered. Otherwise, the text is just measured.

lpFmt

Pointer to a FORMATRANGE structure containing information about the output device, or NULL to free information cached by the control.

This message is typically used with the EM_DISPLAYBAND message to format a rich edit control's contents for an output device such as a printer.

It is very important to free cached information after the last time you use this message. In addition, after using this message for one device, you must free cached information before using it again for a different device.

Return Value

Returns the index of the last character that fits in the region plus one.

See Also

EM_DISPLAYBAND, FORMATRANGE


EM_GETCHARFORMAT  (preliminaryWindows NT)
EM_GETCHARFORMAT  (preliminary−Windows NT)

EM_GETCHARFORMAT

wParam = (WPARAM) (BOOL) fSelection;

lParam = (LPARAM) (CHARFORMAT FAR *) lpFmt;

The EM_GETCHARFORMAT message determines the current character formatting in a rich edit control.

Parameters

fSelection

Value specifying whether to get the default character formatting or the current selection's character formatting. If this parameter is zero, the default formatting is returned. Otherwise, the current selection's formatting is returned.

lpFmt

Pointer to a CHARFORMAT structure to fill in. If the selection formatting is being retrieved, the structure receives the attributes of the first character, and the dwMask member specifies which attributes are consistent throughout the entire selection.

Return Value

Returns the value of the dwMask member of the CHARFORMAT structure.

See Also

CHARFORMAT


EM_GETEVENTMASK  (preliminaryWindows NT)
EM_GETEVENTMASK  (preliminary−Windows NT)

EM_GETEVENTMASK

wParam = 0;  // not used; must be zero

lParam = 0;  // not used; must be zero

The EM_GETEVENTMASK message retrieves the event mask for an rich edit control. The event mask specifies which notification messages the control sends to its parent window.

Return Value

Returns the event mask for the rich edit control.


EM_GETFIRSTVISIBLELINE

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.

Return Value

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

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.

Return Value

The return value is a memory handle identifying the buffer that holds the content of the edit control. If an error occurs, such as sending the message to a single-line edit control, the return value is zero.

Remarks

In a 16-bit Windows-based application, the handle is a local memory handle and can be used only by functions that take a local memory handle as a parameter. The application can send this message to a multiline edit control in a dialog box only if it created the dialog box with the DS_LOCALEDIT style flag set. If the DS_LOCALEDIT style is not set, the return value is still nonzero, but the return value will not be meaningful.

See Also

EM_SETHANDLE


EM_GETLIMITTEXT  (preliminaryWindows 95)
EM_GETLIMITTEXT  [image]  (preliminary−Windows 95)

EM_GETLIMITTEXT

wParam = 0;  // not used, must be zero

lParam = 0;  // not used, must be zero

An application sends the EM_GETLIMITTEXT message to retrieve the current text limit, in characters, for an edit control.

Parameters

This message has no parameters.

Return Value

The return value is the text limit.

See Also

EM_SETLIMITTEXT


EM_GETLINE

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.

Parameters

line

Value of wParam. Specifies the zero-based index of the line to retrieve from a multiline edit control. A value of zero specifies the topmost line. This parameter is ignored by a single-line edit control.

lpch

Value of lParam. Points to the buffer that receives a copy of the line. The first word of the buffer specifies the maximum number of characters that can be copied to the buffer.

Return Value

The return value is the number of characters copied. The return value is zero if the line number specified by the line parameter is greater than the number of lines in the edit control.

Remarks

The copied line does not contain a terminating null character.

See Also

EM_LINELENGTH, WM_GETTEXT


EM_GETLINECOUNT

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.

Return Value

The return value is an integer specifying the number of lines in the multiline edit control. If no text is in the edit control, the return value is 1.

See Also

EM_GETLINE, EM_LINELENGTH


EM_GETMARGINS  (preliminaryWindows 95)
EM_GETMARGINS  [image]  (preliminary−Windows 95)

EM_GETMARGINS

wParam = 0;  // not used, must be zero

lParam = 0;  // not used, must be zero

An application sends the EM_GETMARGINS message to retrieve the widths of the left and right margins for an edit control.

Parameters

This message has no parameters.

Return Value

Returns the width of the left margin in the low-order word, and the width of the right margin in the high-order word.

See Also

EM_SETMARGINS


EM_GETMODIFY

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 content of an edit control has been modified.

Parameters

This message has no parameters.

Return Value

If the content of edit control has been modified, the return value is TRUE; otherwise, it is FALSE.

Remarks

Windows maintains an internal flag indicating whether the content of the edit control has been changed. This flag is cleared when the edit control is first created; alternatively, an application can send an EM_SETMODIFY message to the edit control to clear the flag.

See Also

EM_SETMODIFY


EM_GETOLEINTERFACE  (preliminaryWindows NT)
EM_GETOLEINTERFACE  (preliminary−Windows NT)

EM_GETOLEINTERFACE

wParam = 0;

lParam = (LPARAM) (LPVOID FAR *) ppObject;

The EM_GETOLEINTERFACE message retrieves an IRichEditOle object that a client can use to access a rich edit control's OLE functionality.

Parameters

ppObject

Address at which the control stores a pointer to the IRichEditOle object. The control calls the AddRef function for the object before returning, so the calling application must call the Release function when it is done with the object.

Return Value

Returns a nonzero value if successful, or zero otherwise.


EM_GETPARAFORMAT  (preliminaryWindows NT)
EM_GETPARAFORMAT  (preliminary−Windows NT)

EM_GETPARAFORMAT

wParam = 0;

lParam = (LPARAM) (PARAFORMAT FAR *) lpFmt;

The EM_GETPARAFORMAT message retrieves the paragraph formatting of the current selection in a rich edit control.

Parameters

lpFmt

Pointer to a PARAFORMAT structure that receives the paragraph formatting attributes of the current selection.

If more than one paragraph is selected, the structure receives the attributes of the first paragraph, and the dwMask member specifies which attributes are consistent throughout the entire selection.

Return Value

Returns the value of the dwMask member of the PARAFORMAT structure.

See Also

PARAFORMAT


EM_GETPASSWORDCHAR

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.

Return Value

The return value specifies the character to be displayed in place of the character typed by the user. The return value is NULL if no password character exists.

Remarks

If the edit control is created with the ES_PASSWORD style, the default password character is set to an asterisk (*).

See Also

EM_SETPASSWORDCHAR


EM_GETRECT

EM_GETRECT

wParam = 0;                    // not used; must be zero

lParam (LPARAM) (LPRECT) lprc; // address of structure for rectangle

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.

Parameters

lprc

Value of lParam. Points to the RECT structure that receives the formatting rectangle.

Return Value

The return value is not a meaningful value.

Remarks

You can modify the formatting rectangle of a multiline edit control by using the EM_SETRECT and EM_SETRECTNP messages.

See Also

EM_SETRECT, EM_SETRECTNP, RECT


EM_GETSEL

EM_GETSEL

wParam = (WPARAM) (LPDWORD) lpdwStart; // receives starting position

lParam = (LPARAM) (LPDWORD) lpdwEnd;   // receives ending position

An application sends an EM_GETSEL message to get the starting and ending character positions of the current selection in an edit control.

Parameters

lpdwStart

Value of wParam. Points to a 32-bit value that receives the starting position of the selection. This parameter can be NULL.

lpdwEnd

Value of lParam. Points to a 32-bit value that receives the position of the first nonselected character after the end of the selection. This parameter can be NULL.

Return Value

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_GETSELTEXT  (preliminaryWindows NT)
EM_GETSELTEXT  (preliminary−Windows NT)

EM_GETSELTEXT

wParam = 0;

lParam = (LPARAM) (LPSTR) lpBuf;

The EM_GETSELTEXT message retrieves the currently selected text in a rich edit control.

Parameters

lpBuf

Pointer to a buffer that receives the selected text. The calling application must ensure that the buffer is large enough to hold the selected text.

Return Value

Returns the number of characters copied, not including the terminating null character.


EM_GETTEXTRANGE  (preliminaryWindows NT)
EM_GETTEXTRANGE  (preliminary−Windows NT)

EM_GETTEXTRANGE

wParam = 0;

lParam = (LPARAM) (TEXTRANGE FAR *) lpRange;

The EM_GETTEXTRANGE message retrieves a specified range of characters from a rich edit control.

Parameters

lpRange

Pointer to a TEXTRANGE structure that specifies the range of characters to retrieve and a buffer to copy the characters to.

Return Value

Returns the number of characters copied, not including the terminating null character.

See Also

TEXTRANGE


EM_GETTHUMB  (preliminaryWindows NT)
EM_GETTHUMB  [image]  (preliminary−Windows NT)

EM_GETTHUMB

wParam = 0;  // not used, must be zero

lParam = 0;  // not used, must be zero

An application sends the EM_GETTHUMB message to retrieve the position of the scroll box (thumb) in a multiline edit control.

Parameters

This message has no parameters.

Return Value

The return value is the position of the scroll box.


EM_GETWORDBREAKPROC

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.

Return Value

The return value specifies the address of the application-defined wordwrap function. The return value is NULL if no wordwrap function exists.

Remarks

A wordwrap function scans a text buffer that contains text to be sent to the display, looking for the first word that does not fit on the current display line. The wordwrap function places this word at the beginning of the next line on the display. A wordwrap function defines the point at which Windows should break a line of text for multiline edit controls, usually at a space character that separates two words.

See Also

EditWordBreakProc, EM_FMTLINES, EM_SETWORDBREAKPROC


EM_HIDESELECTION  (preliminaryWindows NT)
EM_HIDESELECTION  (preliminary−Windows NT)

EM_HIDESELECTION

wParam = (WPARAM) (BOOL) fHide;

lParam = (LPARAM) (BOOL) fChangeStyle;

The EM_HIDESELECTION message hides or shows the selection in a rich edit control.

Parameters

fHide

Value specifying whether to hide or show the selection. If this parameter is zero, the selection is shown. Otherwise, the selection is hidden.

fChangeStyle

Value specifying whether to change the control's ES_NOHIDESEL window style. If this parameter is zero, the selection is temporarily shown or hidden. Otherwise, the style is changed.

If this parameter is nonzero and the control has the focus, the selection is hidden or shown as appropriate.

Return Value

No return value.


EM_LIMITTEXT

EM_LIMITTEXT

wParam = (WPARAM) cchMax;   // text length, in characters

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.

Parameters

cchMax

Value of wParam. Specifies the maximum number of characters the user can enter. If this parameter is zero, the text length is set to 0x7FFFFFFE characters for single-line edit controls or 0xFFFFFFFF for multiline edit controls.

Return Value

This message does not return a value.

Remarks

The EM_LIMITTEXT message limits only the text the user can enter. It has no effect on any text already in the edit control when the message is sent, nor does it affect the length of the text copied to the edit control by the WM_SETTEXT message. If an application uses the WM_SETTEXT message to place more text into an edit control than is specified in the EM_LIMITTEXT message, the user can edit the entire contents of the edit control.

The default limit to the amount of text a user can enter in an edit control is 30,000 characters.

See Also

WM_SETTEXT


EM_LINEFROMCHAR

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.

Parameters

ich

Value of wParam. Specifies the character index of the character contained in the line whose number is to be retrieved. If the ich parameter is −1, either the line number of the current line (the line containing the caret) is retrieved or, if there is a selection, the line number of the line containing the beginning of the selection is retrieved.

Return Value

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

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.

Parameters

line

Value of wParam. Specifies the zero-based line number. A value of −1 specifies the current line number (the line that contains the caret).

Return Value

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

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.

Parameters

ich

Value of wParam. Specifies the character index of a character in the line whose length is to be retrieved when EM_LINELENGTH is sent to a multiline edit control. If this parameter is −1, the message returns the number of unselected characters on lines containing selected characters. For example, if the selection extended from the fourth character of one line through the eighth character from the end of the next line, the return value would be 10 (three characters on the first line and seven on the next).

Return Value

The return value is the length, in characters, of the line specified by the ich parameter when an EM_LINELENGTH message is sent to a multiline edit control. The return value is the length, in characters, of the text in the edit control when an EM_LINELENGTH message is sent to a single-line edit control.

Remarks

Use the EM_LINEINDEX message to retrieve a character index for a given line number within a multiline edit control.

See Also

EM_LINEINDEX


EM_LINESCROLL

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.

Parameters

cxScroll

Value of wParam. Specifies the number of characters to scroll horizontally.

cyScroll

Value of lParam. Specifies the number of lines to scroll vertically.

Return Value

If the message is sent to a multiline edit control, the return value is TRUE; if the message is sent to a single-line edit control, the return value is FALSE.

Remarks

The edit control does not scroll vertically past the last line of text in the edit control. If the current line plus the number of lines specified by the cyScroll parameter exceeds the total number of lines in the edit control, the value is adjusted so that the last line of the edit control is scrolled to the top of the edit-control window.

The EM_LINESCROLL message can be used to scroll horizontally past the last character of any line.


EM_PASTESPECIAL  (preliminaryWindows NT)
EM_PASTESPECIAL  (preliminary−Windows NT)

EM_PASTESPECIAL

wParam = (WPARAM) (UINT) uFormat;

lParam = 0;

The EM_PASTESPECIAL message pastes a specific clipboard format in a rich edit control.

Parameters

uFormat

Clipboard format to paste. For a list of clipboard formats, see SetClipboardData.

Return Value

No return value.

See Also

SetClipboardData


EM_POSFROMCHAR  (preliminaryWindows 95)
EM_POSFROMCHAR  [image]  (preliminary−Windows 95)

EM_POSFROMCHAR

wParam = (WPARAM)wCharIndex;   // zero-based index of character

lParam = 0;                    // not used, must be zero

An application sends the EM_POSFROMCHAR message to retrieve the coordinates of the specified character in an edit control.

Parameters

wCharIndex

Value of wParam. Specifies the zero-based index of the character.

Return Value

The return value specifies the coordinates of the upper-left corner of the character. If wCharIndex is greater than the index of the last character in the control, the return value specifies the coordinates of the position just past the last character in the control. The x-coordinate is in the low-order word and the y-coordinate is in the high-order word. The coordinates are relative to the upper-left corner of the edit control's client area.

Remarks

For a single-line edit control, the y-coordinate is always zero. A returned coordinate can be negative if the character has been scrolled outside the edit control's client area. The coordinates are truncated to integer values.

See Also

EM_CHARFROMPOS


EM_REPLACESEL

EM_REPLACESEL

fCanUndo = (BOOL) wParam ;          // flag that specifies whether replacement can be undone

lpszReplace = (LPCTSTR) lParam ;  // pointer to replacement text string

An application sends an EM_REPLACESEL message to replace the current selection in an edit control with the specified text.

Parameters

fCanUndo

Value of wParam. Specifies whether the replacement operation can be undone. If this is TRUE, the operation can be undone. If this is FALSE , the operation cannot be undone.

lpszReplace

Value of lParam. Points to a null-terminated string containing the replacement text.

Return Value

This message does not return a value.

Remarks

Use the EM_REPLACESEL message to replace only a portion of the text in an edit control. To replace all of the text, use the WM_SETTEXT message.

If there is no current selection, the replacement text is inserted at the current location of the caret.

See Also

WM_SETTEXT


EM_REQUESTRESIZE  (preliminaryWindows NT)
EM_REQUESTRESIZE  (preliminary−Windows NT)

EM_REQUESTRESIZE

wParam = 0;

lParam = 0;

The EM_REQUESTRESIZE message forces a rich edit control to send an EN_REQUESTRESIZE notification message to its parent window.

Return Value

No return value.

Remarks

This message is useful during WM_SIZE processing for the parent of a bottomless rich edit control.

See Also

EN_REQUESTRESIZE, WM_SIZE


EM_SCROLL

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.

Parameters

nScroll

Value of wParam. Specifies the action the scroll bar is to take. This parameter may be one of the following values:

Value	Meaning
SB_LINEDOWN	Scrolls down one line.
SB_LINEUP	Scrolls up one line.
SB_PAGEDOWN	Scrolls down one page.
SB_PAGEUP	Scrolls up one page.
Return Value

If the message is successful, the high-order word of the return value is TRUE, and the low-order word is the number of lines that the command scrolls. The number returned may not be the same as the actual number of lines scrolled if the scrolling moves to the beginning or the end of the text. If the nScroll parameter specifies an invalid value, the return value is FALSE.

Remarks

An application should use the EM_LINESCROLL message to scroll to a specific line or character position.

An application should use the EM_SCROLLCARET message to scroll the caret into view.

See Also

EM_LINESCROLL, EM_SCROLLCARET, WM_VSCROLL


EM_SCROLLCARET

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.

Parameters

wParam

This parameter is currently unused. It is reserved for future use. It should be set to zero.

lParam

This parameter is currently unused. It is reserved for future use. It should be set to zero.

Return Value

The return value is nonzero if the message is sent to an edit control.

Remarks

In previous versions of Windows, scrolling the caret into view was done by specifying wParam = FALSE in the EM_SETSEL message. A Win32-based application should use the EM_SCROLLCARET message to scroll the caret into view.

See Also

EM_SETSEL


EM_SELECTIONTYPE  (preliminaryWindows NT)
EM_SELECTIONTYPE  (preliminary−Windows NT)

EM_SELECTIONTYPE

wParam = 0;

lParam = 0;

The EM_SELECTIONTYPE message determines the selection type for a rich edit control.

Return Value

Returns SEL_EMPTY if the selection is empty, or one or more of the following values:

Value	Contents of the selection
SEL_TEXT	Text
SEL_OBJECT	At least one OLE object
SEL_MULTICHAR	More than one character of text
SEL_MULTIOBJECT	More than one OLE object
Remarks

This message is useful during WM_SIZE processing for the parent of a bottomless rich edit control.

See Also

WM_SIZE


EM_SETBKGNDCOLOR  (preliminaryWindows NT)
EM_SETBKGNDCOLOR  (preliminary−Windows NT)

EM_SETBKGNDCOLOR

wParam = (WPARAM) (BOOL) fUseSysColor;

lParam = (LPARAM) (COLORREF) clr;

The EM_SETBKGNDCOLOR message sets the background color for a rich edit control.

Parameters

fUseSysColor

Value specifying whether to use the system color. If this parameter is nonzero, the background is set to the window background system color. Otherwise, the background is set to the specified color.

clr

COLORREF structure specifying the color if fUseSysColor is zero.

Return Value

Returns the old background color.

See Also

COLORREF


EM_SETCHARFORMAT  (preliminaryWindows NT)
EM_SETCHARFORMAT  (preliminary−Windows NT)

EM_SETCHARFORMAT

wParam = (WPARAM) (UINT) uFlags;

lParam = (LPARAM) (CHARFORMAT FAR *) lpFmt;

The EM_SETCHARFORMAT message sets character formatting in a rich edit control.

Parameters

uFlags

Character formatting that applies to the control. This parameter can be zero or more of these values:

Value	Meaning
SCF_SELECTION	Applies the formatting to the current selection, or sets the default formatting if the selection is empty.
SCF_WORD	Applies the formatting to the selected word or words. If the selection is empty but the insertion point is inside a word, the formatting is applied to the word. This value must be used in conjunction with the SCF_SELECTION value.
lpFmt

Pointer to a CHARFORMAT structure specifying the character formatting to use. Only the formatting attributes specified by the dwMask member are changed.

Return Value

Returns a nonzero value if successful or zero otherwise.

Remarks

If this parameter is zero, the default character formatting is used.

See Also

CHARFORMAT


EM_SETEVENTMASK  (preliminaryWindows NT)
EM_SETEVENTMASK  (preliminary−Windows NT)

EM_SETEVENTMASK

wParam = 0;

lParam = (LPARAM) (DWORD) dwMask;

The EM_SETEVENTMASK message sets the event mask for a rich edit control. The event mask specifies which notification messages the control sends to its parent window.

Parameters

dwMask

New event mask for the rich edit control.

Return Value

Returns the previous event mask.


EM_SETHANDLE

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.

Parameters

hloc

Value of wParam. Identifies the memory the edit control uses to store the currently displayed text instead of allocating its own memory. If necessary, the control reallocates this memory.

Return Value

This message does not return a value.

Remarks

Before an application sets a new memory handle, it should send an EM_GETHANDLE message to retrieve the handle of the current memory buffer and should free that memory.

An edit control automatically reallocates the given buffer whenever it needs additional space for text, or it removes enough text so that additional space is no longer needed.

Sending an EM_SETHANDLE message clears the undo buffer (EM_CANUNDO returns zero) and the internal modification flag (EM_GETMODIFY returns zero). The edit control window is redrawn.

An application can send this message to a multiline edit control in a dialog box only if it has created the dialog box with the DS_LOCALEDIT style flag set.

See Also

EM_CANUNDO, EM_GETHANDLE, EM_GETMODIFY


EM_SETLIMITTEXT  (preliminaryWindows 95)
EM_SETLIMITTEXT  [image]  (preliminary−Windows 95)

EM_SETLIMITTEXT

wParam = (WPARAM) cbMax;    // new text limits, in bytes

lParam = 0;                 // not used, must be zero

An application sends the EM_SETLIMITTEXT message to set the text limit for an edit control. The text limit is the maximum amount of text, in bytes, that the edit control can contain.

Parameters

cbMax

Value of wParam. Specifies the new text limit, in bytes. If this parameter is 0, Windows sets the maximum text limit. The maximum text limit is 32,766 bytes for a single-line edit control, and 65,535 bytes for a multiline edit control.

Return Value

This message does not return a value.

Remarks

The EM_SETLIMITTEXT message replaces the EM_LIMITTEXT message.

See Also

EM_GETLIMITTEXT


EM_SETMARGINS  (preliminaryWindows 95)
EM_SETMARGINS  [image]  (preliminary−Windows 95)

EM_SETMARGINS

wParam = (WPARAM) fwMargin;	// left and/or right margins

lParam = (LPARAM) MAKELONG(wLeft, wRight);	// width of left or right margins, in pixels

An application sends the EM_SETMARGINS message to set the widths of the left and right margins for an edit control. The message redraws the control to reflect the new margins.

Parameters

fwMargin

Value of wParam. Specifies the margins to set. This parameter can be a combination of the following values:

Value	Meaning
EC_LEFTMARGIN	Sets the left margin.
EC_RIGHTMARGIN	Sets the right margin.
EC_USEFONTINFO	Uses information about the current font of the edit control to set the margins. For a single-line edit control, margins are set to the average width of characters in the font. For a multiline edit control, the right margin is set to the "A" width of the font (the distance added to the current position before drawing a character), and the left margin is set to the "C" width (the distance added to the current position to provide white space to the right of a character).
If EC_USEFONTINFO is specified, the lParam parameter is ignored.

wLeft

Value of the low-order word of lParam. Specifies the width of the left margin, in pixels. This value is ignored if fwMargin does not include EC_LEFTMARGIN or if EC_USEFONTINFO is specified.

wRight

Value of the high-order word of lParam. Specifies the width of the right margin, in pixels. This value is ignored if fwMargin does not include EC_RIGHTMARGIN or if EC_USEFONTINFO is specified.

Return Value

This message does not return a value.

See Also

EM_GETMARGINS


EM_SETMODIFY

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.

Parameters

fModified

Value of wParam. Specifies the new value for the modification flag. A value of TRUE indicates the text has been modified, and a value of FALSE indicates it has not been modified.

Return Value

This message does not return a value.

See Also

EM_GETMODIFY


EM_SETOLEINTERFACE  (preliminaryWindows NT)
EM_SETOLEINTERFACE  (preliminary−Windows NT)

EM_SETOLEINTERFACE

wParam = 0;

lParam = (LPARAM) (IRichEditOleCallback FAR *) lpObj;

The EM_SETOLEINTERFACE message gives a rich edit control an IRichEditOleCallback object that the control uses to get OLE-related resources and information from the client.

Parameters

lpObj

Pointer to an IRichEditOleCallback object. The control calls the AddRef function for the object before returning.

Return Value

Returns a nonzero value if successful or zero otherwise.


EM_SETPARAFORMAT  (preliminaryWindows NT)
EM_SETPARAFORMAT  (preliminary−Windows NT)

EM_SETPARAFORMAT

wParam = 0;  // not used; must be zero

lParam = (LPARAM) (PARAFORMAT FAR *) lpFmt;

The EM_SETPARAFORMAT message sets the paragraph formatting for the current selection in a rich edit control.

Parameters

lpFmt

Pointer to a PARAFORMAT structure specifying the new paragraph formatting attributes. Only the attributes specified by the dwMask member are changed.

Return Value

Returns a nonzero value if successful, or zero otherwise.

See Also

PARAFORMAT


EM_SETPASSWORDCHAR

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 the password character for a single-line edit control when the user types text. When a password character is set, that character is displayed in place of each character the user types.

Parameters

ch

Value of wParam. Specifies the character to be displayed in place of the character typed by the user. If this parameter is zero, the characters typed by the user are displayed.

Return Value

This message does not return a value.

Remarks

When the EM_SETPASSWORDCHAR message is received by an edit control, the edit control redraws all visible characters by using the character specified by the ch parameter.

If the edit control is created with the ES_PASSWORD style, the default password character is set to an asterisk (*). This style is removed if an EM_SETPASSWORDCHAR message is sent with the ch parameter set to zero.

See Also

EM_GETPASSWORDCHAR


EM_SETREADONLY

EM_SETREADONLY

wParam = (WPARAM) (BOOL) fReadOnly;  // read-only flag

lParam = 0;                          // 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.

Parameters

fReadOnly

Value of wParam. Specifies whether to set or remove the ES_READONLY style. A value of TRUE sets the ES_READONLY style; a value of FALSE removes the ES_READONLY style.

Return Value

If the operation succeeds, the return value is nonzero; otherwise, it is zero.

Remarks

When an edit control has the ES_READONLY style, the user cannot change the text within the edit control.

To determine whether an edit control has the ES_READONLY style, use the GetWindowLong function with the GWL_STYLE flag.

See Also

GetWindowLong


EM_SETRECT

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.

Parameters

lprc

Value of lParam. Points to a RECT structure that specifies the new dimensions of the rectangle.

Return Value

This message does not return a value.

Remarks

The EM_SETRECT message causes the text of the edit control to be redrawn. To change the size of the formatting rectangle without redrawing the text, use the EM_SETRECTNP message.

If the edit control does not have a horizontal scroll bar, and the formatting rectangle is set to be larger than the edit control window, lines of text exceeding the width of the edit control window (but smaller than the width of the formatting rectangle) are clipped instead of wrapped.

If the edit control contains a border, the formatting rectangle is reduced by the size of the border. If you are adjusting the rectangle returned by an EM_GETRECT message, you must remove the size of the border before using the rectangle with the EM_SETRECT message.

See Also

EM_GETRECT, EM_SETRECTNP, RECT


EM_SETRECTNP

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.

Parameters

lprc

Value of lParam. Points to a RECT structure that specifies the new dimensions of the rectangle.

Return Value

This message does not return a value.

See Also

EM_SETRECT, RECT


EM_SETSEL

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.

Parameters

nStart

Value of wParam. Specifies the starting character position of the selection.

nEnd

Specifies the ending character position of the selection.

Return Value

This message does not return a value.

Remarks

If the nStart parameter is 0 and the nEnd parameter is −1, all the text in the edit control is selected. If nStart is −1, any current selection is removed. The caret is placed at the end of the selection indicated by the greater of the two values nEnd and nStart.

In previous versions of Windows, the wParam parameter is a flag that is set to FALSE to scroll the caret into view or set to TRUE to omit the scrolling. A Win32-based application should use the EM_SCROLLCARET message to scroll the caret into view.

In earlier versions of Windows, the starting and ending positions of the selection are indicated by the low- and high-order words, respectively, of the lParam parameter.

See Also

EM_GETSEL, EM_REPLACESEL, EM_SCROLLCARET


EM_SETTABSTOPS

EM_SETTABSTOPS

wParam = (WPARAM) cTabs;             // number of tab stops

lParam = (LPARAM) (LPDWORD) lpdwTabs;  // 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.

Parameters

cTabs

Value of wParam. Specifies the number of tab stops contained in the lpdwTabs parameter. If this parameter is zero, the lpdwTabs parameter is ignored and default tab stops are set at every 32 dialog box units. If this parameter is 1, tab stops are set at every n dialog box units, where n is the distance pointed to by the ldpwTabs parameter. If the cTabs parameter is greater than 1, lpdwTabs points to an array of tab stops.

lpdwTabs

Value of lParam. Points to an array of unsigned integers specifying the tab stops, in dialog units. If the cTabs parameter is 1, lpdwTabs points to an unsigned integer containing the distance between all tab stops, in dialog box units.

Return Value

If all the tabs are set, the return value is TRUE; otherwise, it is FALSE.

Remarks

The EM_SETTABSTOPS message does not automatically redraw the edit control window. If the application is changing the tab stops for text already in the edit control, it should call the InvalidateRect function to redraw the edit control window.

See Also

GetDialogBaseUnits, InvalidateRect


EM_SETTARGETDEVICE  (preliminaryWindows NT)
EM_SETTARGETDEVICE  (preliminary−Windows NT)

EM_SETTARGETDEVICE

wParam = (WPARAM) (HDC) hdcTarget;

lParam = (LPARAM) (int) cxLineWidth;

The EM_SETTARGETDEVICE message sets the target device and line width used for WYSIWYG (what you see is what you get) formatting in a rich edit control.

Parameters

hdcTarget

Handle to a device context for the target device.

cxLineWidth

Line width to use for formatting.

Return Value

Returns a nonzero value if successful or zero otherwise.


EM_SETWORDBREAK

The EM_SETWORDBREAK message is not supported. Applications that must replace the default wordwrap function of a multiline edit control with an application-defined wordwrap function should use the EM_SETWORDBREAKPROC message.


EM_SETWORDBREAKPROC

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.

Parameters

ewbprc

Value of lParam. Specifies the address of the application-defined wordwrap function. For more information about breaking lines, see the description of the EditWordBreakProc callback function.

Return Value

This message does not return a value.

Remarks

A wordwrap function scans a text buffer that contains text to be sent to the screen, looking for the first word that does not fit on the current screen line. The wordwrap function places this word at the beginning of the next line on the screen.

A wordwrap function defines the point at which Windows should break a line of text for multiline edit controls, usually at a space character that separates two words. Either a multiline or a single-line edit control might call this function when the user presses arrow keys in combination with the CTRL key to move the caret to the next word or previous word. The default wordwrap function breaks a line of text at a space character. The application-defined function may define the wordwrap to occur at a hyphen or a character other than the space character.

See Also

EditWordBreakProc, EM_FMTLINES, EM_GETWORDBREAKPROC


EM_STREAMIN  (preliminaryWindows NT)
EM_STREAMIN  (preliminary−Windows NT)

EM_STREAMIN

wParam = (WPARAM) (UINT) uFormat;

lParam = (LPARAM) (EDITSTREAM FAR *) lpStream;

The EM_STREAMIN message replaces the contents of a rich edit control with the specified data stream.

Parameters

uFormat

One of the following data formats, optionally combined with the SFF_SELECTION flag:

Value	Meaning
SF_TEXT	Text
SF_RTF	Rich-text format
If the SFF_SELECTION flag is specified, the stream replaces the contents of the current selection. Otherwise, the stream replaces the entire contents of the control.

lpStream

Pointer to an EDITSTREAM structure. The control reads (streams in) the data by repeatedly calling the function specified by the structure's pfnCallback member.

Return Value

Returns the number of characters read.

See Also

EDITSTREAM


EM_STREAMOUT  (preliminaryWindows NT)
EM_STREAMOUT  (preliminary−Windows NT)

EM_STREAMOUT

wParam = (WPARAM) (UINT) uFormat;

lParam = (LPARAM) (EDITSTREAM FAR *) lpStream;

The EM_STREAMOUT message writes (streams out) the contents of a rich edit control to the specified data stream.

Parameters

uFormat

Value specifying one of the following data formats, optionally combined with the SFF_SELECTION flag:

Value	Meaning
SF_TEXT	Text with spaces in place of OLE objects
SF_RTF	Rich-text format (RTF)
SF_RTFNOOBJS	RTF with spaces in place of OLE object.
SF_TEXTIZED	Text with a text representation of OLE objects.
The SF_RTFNOOBJS option is useful if an application stores OLE objects itself, as RTF representation of OLE objects is not very compact.

If the SFF_SELECTION flag is specified, only the contents of the current selection are streamed out. Otherwise, the entire contents of the control are streamed out.

lpStream

Pointer to an EDITSTREAM structure. The control streams out the data by repeatedly calling the function specified by the structure's pfnCallback member.

Return Value

Returns the number of characters written to the data stream.

See Also

EDITSTREAM


EM_UNDO

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.

Return Value

For a single-line edit control, the return value is always TRUE. For a multiline edit control, the return value is TRUE if the undo operation is successful, or FALSE if the undo operation fails.

Remarks

An undo operation can also be undone. For example, you can restore deleted text with the first EM_CANUNDO message, and remove the text again with a second EM_CANUNDO message as long as there is no intervening edit operation.

See Also

EM_CANUNDO


EN_CHANGE

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_DROPFILES  (preliminaryWindows NT)
EN_DROPFILES  (preliminary−Windows NT)

EN_DROPFILES

wParam = (WPARAM) (UINT) uID;

lParam = (LPARAM) (ENDROPFILES FAR *) lpEnDropFiles;

The EN_DROPFILE notification message notifies a rich edit control's parent window that the user is attempting to drop files into the control. A rich edit control sends this notification message in the form of a WM_NOTIFY message when it receives the WM_DROPFILES message.

Parameters

uID

Identifier of the rich edit control.

lpEnDropFiles

Pointer to an ENDROPFILES structure.

Return Value

Returns a nonzero value to allow the drop operation or zero to ignore the drop.

Remarks

For a rich edit control to receive WM_DROPFILES messages, the parent window must register the control as a drop target by using the DragAcceptFiles function. The control does not register itself.

See Also

DragAcceptFiles, ENDROPFILES, WM_DROPFILES, WM_NOTIFY


EN_ERRSPACE

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

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

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.

Remarks

In previous versions of Windows, the notification code was in HIWORD(lParam).

See Also

EN_SETFOCUS, WM_COMMAND


EN_MAXTEXT

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

WM_COMMAND


EN_MSGFILTER  (preliminaryWindows NT)
EN_MSGFILTER  (preliminary−Windows NT)

EN_MSGFILTER

wParam = (WPARAM) (UINT) uID;

lParam = (LPARAM) (MSGFILTER) lpMsgFilter;

The EN_MSGFILTER notification message notifies a rich edit control's parent window of a keyboard or mouse event in the control. A rich edit control sends this notification message in the form of a WM_NOTIFY message.

Parameters

uID

Identifier of the rich edit control.

lpMsgFilter

Pointer to a MSGFILTER structure containing information about the keyboard or mouse message. If the parent window modifies this structure and returns a nonzero value, the modified message is processed instead of the original one.

Return Value

Returns a nonzero value if the control should process the event, or zero if the control should ignore the event.

See Also

MSGFILTER, WM_NOTIFY


EN_PROTECTED  (preliminaryWindows NT)
EN_PROTECTED  (preliminary−Windows NT)

EN_PROTECTED

wParam = (WPARAM) (UINT) uID;

lParam = (LPARAM) (ENPROTECTED FAR *) lpEnProtected;

The EN_PROTECTED notification message notifies a rich edit control's parent window that the user is taking an action that would change a protected range of text. A rich edit control sends this notification message in the form of a WM_NOTIFY message.

Parameters

uID

Identifier of the rich edit control.

lpEnProtected

Pointer to an ENPROTECTED structure containing information about the message that triggered the notification.

Return Value

Returns zero to allow the operation or a nonzero value to prevent it.

Remarks

If zero is returned and the msg, wParam, and lParam members of the ENPROTECTED structure are changed, the control processes the revised message instead of the original message.

See Also

ENPROTECTED, WM_NOTIFY


EN_REQUESTRESIZE  (preliminaryWindows NT)
EN_REQUESTRESIZE  (preliminary−Windows NT)

EN_REQUESTRESIZE

wParam = (WPARAM) (UINT) uID;

lParam = (LPARAM) (REQRESIZE FAR *) lpReSize;

The EN_REQUESTRESIZE notification message notifies a rich edit control's parent window that the control's contents are either smaller or larger than the control's window size. A rich edit control sends this notification message in the form of a WM_NOTIFY message.

Parameters

uID

Identifier of the rich edit control.

lpReSize

Pointer to a REQRESIZE structure.

Return Value

No return value.

Remarks

To support the bottomless behavior of a rich edit control, the parent window must resize the control when it receives this notification message.

See Also

REQRESIZE, WM_NOTIFY


EN_SELCHANGE  (preliminaryWindows NT)
EN_SELCHANGE  (preliminary−Windows NT)

EN_SELCHANGE

wParam = (WPARAM) (UINT) uID;

lParam = (LPARAM) (SELCHANGE FAR *) lpSelChange;

The EN_SELCHANGE notification message notifies a rich edit control's parent window that the current selection has changed. A rich edit control sends this notification message in the form of a WM_NOTIFY message.

Parameters

uID

Identifier of the rich edit control.

lpSelChange

Pointer to a SELCHANGE structure.

Return Value

No return value.

See Also

SELCHANGE, WM_NOTIFY


EN_SETFOCUS

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.

Remarks

In previous versions of Windows, the notification code was in HIWORD(lParam).

See Also

EN_KILLFOCUS, WM_COMMAND


EN_UPDATE

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 message is sent after the control has formatted the text, but before it displays the text. This makes it possible to resize the edit control window, if necessary. The parent window of the edit control receives this notification message through the WM_COMMAND message.

See Also

EN_CHANGE, WM_COMMAND


EN_VSCROLL

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

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.

Parameters

lpfmsgdi

Value of lParam. Points to an FMS_GETDRIVEINFO structure that receives drive information.

Return Value

The return value is always nonzero.

Remarks

If 0xFFFFFFFF is returned in the dwTotalSpace or dwFreeSpace member of the FMS_GETDRIVEINFO structure, the extension library must compute the value or values.

See Also

FMExtensionProc, FMS_GETDRIVEINFO


FM_GETFILESEL

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).

Parameters

index

Value of wParam. Specifies the zero-based index of the selected file to retrieve.

lpfmsgfs

Value of lParam. Points to an FMS_GETFILESEL structure that receives information about the selection.

Return Value

The return value is the zero-based index of the selected file that was retrieved.

Remarks

An extension can use the FM_GETSELCOUNT message to get the count of selected files.

See Also

FMExtensionProc, FMS_GETFILESEL, FM_GETFILESELLFN, FM_GETSELCOUNT, FM_GETSELCOUNTLFN


FM_GETFILESELLFN

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the selected file to retrieve.

lpfmsgfs

Value of lParam. Points to an FMS_GETFILESEL structure that receives information about the selection.

Return Value

The return value is the zero-based index of the selected file that was retrieved.

Remarks

Only extensions that support long filenames (for example, network-aware extensions) should use this message.

An extension can use the FM_GETSELCOUNT message to get the count of selected files.

See Also

FMExtensionProc, FM_GETFILESEL, FM_GETSELCOUNT, FM_GETSELCOUNTLFN


FM_GETFOCUS

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.

Return Value

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

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.

Return Value

The return value is the number of selected files.

See Also

FM_GETFILESEL, FM_GETFILESELLFN, FM_GETSELCOUNTLFN


FM_GETSELCOUNTLFN

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.

Return Value

The return value is the number of selected files.

Remarks

Only extensions that support long filenames (for example, network-aware extensions) should use this message.

See Also

FM_GETFILESEL, FM_GETFILESELLFN, FM_GETSELCOUNT


FM_REFRESH_WINDOWS

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.

Parameters

fRepaint

Value of wParam. Specifies whether File Manager repaints its active window or all of its windows. If this parameter is TRUE, File Manager repaints all of its windows. Otherwise, File Manager repaints only its active window.

Return Value

This message does not return a meaningful value.

Remarks

File-system changes caused by an extension are automatically detected by File Manager. An extension should use this message only in situations where drive connections are made or canceled.

See Also

FMExtensionProc


FM_RELOAD_EXTENSIONS

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.

Return Value

This message does not return a meaningful value.

Remarks

Other applications can use the PostMessage function to send this message to File Manager. To obtain the appropriate File Manager window handle, an application can specify "WFS_Frame" as the lpszClassName parameter in a call to the FindWindow function.

See Also

FindWindow, FMExtensionProc, PostMessage


FMEVENT_HELPMENUITEM

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.

Parameters

uItem

Identifies the menu or toolbar command item for which help is sought. The extension procedure uses this value to determine how best to call WinHelp.

Return Value

An extension DLL procedure should return zero if it processes this message.

See Also

FMExtensionProc, WinHelp, FMEVENT_HELPSTRING


FMEVENT_HELPSTRING

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.

Parameters

lpfmshs

Points to an FMS_HELPSTRING structure that communicates command item help string data.

The FMS_HELPSTRING structure identifies the command item for which a help string is wanted, along with a handle to its menu. An application then writes the appropriate help string to the FMS_HELPSTRING structure's szHelp member.

Return Value

An extension DLL procedure should return zero if it processes this message.

See Also

FMExtensionProc, FMEVENT_HELPMENUITEM


FMEVENT_INITMENU

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.

Parameters

hmenu

Specifies the handle of the File Manager menu bar.

Return Value

An extension DLL should return zero if it processes this message.

Remarks

An extension DLL receives this message only when the user selects the top-level menu. If the extension contains submenus, it must initialize them at the same time it initializes the top-level menu.

See Also

FMExtensionProc


FMEVENT_LOAD

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.

Parameters

lpfmsld

Points to an FMS_LOAD structure that specifies the menu-item delta value. An extension DLL should save the menu-item delta value and fill the other structure members with information about the extension.

Return Value

An extension DLL must return TRUE to continue loading the DLL. If the DLL returns FALSE, File Manager calls the FreeLibrary function and ends any communication with the extension DLL.

Remarks

An application should fill the dwSize, szMenuName, and hMenu members in the FMS_LOAD structure. It should also save the value of the wMenuDelta member and use it to identify menu items when modifying the menu.

See Also

FMExtensionProc, FMS_LOAD, FreeLibrary


FMEVENT_SELCHANGE

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.

Return Value

An extension DLL should return zero if it processes this message.

Remarks

Changes in the tree portion of the directory window do not produce this message.

Because the user can change the selection many times, the extension DLL must return promptly after processing this message to avoid slowing the selection process for the user.

See Also

FMExtensionProc


FMEVENT_TOOLBARLOAD

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.

Parameters

lpfmstbl

Points to an FMS_TOOLBARLOAD structure. If the extension DLL adds a button to the toolbar in File Manager, the DLL should fill the structure with information about the button.

.

Return Value

An extension DLL must return TRUE to add the button to the toolbar. If the DLL returns FALSE, File Manager does not add the button.

See Also

FMExtensionProc, FMS_TOOLBARLOAD


FMEVENT_UNLOAD

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.

Return Value

An extension DLL should return zero if it processes this message.

Remarks

The hwnd and hMenu values passed with the FMEVENT_LOAD and FMEVENT_INITMENU messages may not be valid at the time this message is sent.

See Also

FMExtensionProc


FMEVENT_USER_REFRESH

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.

Return Value

An extension DLL should return zero if it processes this message.

See Also

FMExtensionProc


HDM_DELETEITEM  (preliminaryWindows NT)
HDM_DELETEITEM  (preliminary−Windows NT)

HDM_DELETEITEM

wParam = (WPARAM) (int) index;

lParam = 0;

// Corresponding macro

BOOL Header_DeleteItem(hwndHD, index);

The HDM_DELETEITEM message deletes an item from a header control.

Parameters

hwndHD

Handle to the header control.

index

Index of the item to delete.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.


HDM_GETITEM  (preliminaryWindows NT)
HDM_GETITEM  (preliminary−Windows NT)

HDM_GETITEM

wParam = (WPARAM) (int) index;

lParam = (LPARAM) (HD_ITEM FAR*) phdi;

// Corresponding macro

BOOL Header_GetItem(hwndHD, index, phdi);

The HDM_GETITEM message retrieves information about an item in a header control.

Parameters

hwndHD

Handle to the header control.

index

Index of the item for which information is to be retrieved.

phdi

Pointer to an HD_ITEM structure. When the message is sent, the mask member indicates the type of information being requested. When the message returns, the other members receive the requested information. If the mask member specifies zero, the message returns TRUE but copies no information to the structure.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

See Also

HD_ITEM


HDM_GETITEMCOUNT  (preliminaryWindows NT)
HDM_GETITEMCOUNT  (preliminary−Windows NT)

HDM_GETITEMCOUNT

wParam = 0;

lParam = 0;

// Corresponding macro

int Header_GetItemCount(hwndHD);

The HDM_GETITEMCOUNT message retrieves a count of the items in a header control.

Parameters

hwndHD

Handle to the header control.

Return Value

If the operation succeeds, the return value is the number of items.

If the operation fails, the return value is − 1.


HDM_HITTEST  (preliminaryWindows NT)
HDM_HITTEST  (preliminary−Windows NT)

HDM_HITTEST

wParam = 0;

lParam = (LPARAM) (HD_HITTESTINFO FAR *) phdhti;

The HDM_HITTEST message tests a point to determine which header item, if any, is at the specified point.

Parameters

phdhti

Pointer to an HD_HITTESTINFO structure that contains the position to test and receives information about the results of the test.

Return Value

Returns the index of the item at the specified position, if any, or  − 1 otherwise.

See Also

HD_HITTESTINFO


HDM_INSERTITEM  (preliminaryWindows NT)
HDM_INSERTITEM  (preliminary−Windows NT)

HDM_INSERTITEM

wParam = (WPARAM) (int) index;

lParam = (LPARAM) (const HD_ITEM FAR*) phdi;

// Corresponding macro

int Header_InsertItem(hwndHD, index, phdi);

The HDM_INSERTITEM message inserts a new item into a header control.

Parameters

hwndHD

Handle to the header control.

index

Index of the item after which the new item is to be inserted. The new item is inserted at the end of the header control if index is greater than or equal to the number of items in the control. If index is zero, the new item is inserted at the beginning of the header control.

phdi

Pointer to an HD_ITEM structure that contains information about the new item.

Return Value

If the operation succeeds, the return value is the index of the new item.

If the operation fails, the return value is − 1.

See Also

HD_ITEM


HDM_LAYOUT  (preliminaryWindows NT)
HDM_LAYOUT  (preliminary−Windows NT)

HDM_LAYOUT

wParam = 0;

lParam = (LPARAM) (HD_LAYOUT FAR*) playout;

// Corresponding macro

BOOL Header_Layout(hwndHD, playout);

The HDM_LAYOUT message retrieves the size and position of a header control within a given rectangle. This message is used to determine the appropriate dimensions for a new header control that is to occupy the given rectangle.

Parameters

hwndHD

Handle to the header control.

playout

Pointer to an HD_LAYOUT structure. The prc member specifies the coordinates of a rectangle, and the pwpos member receives the size and position for the header control within the rectangle.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

See Also

HD_LAYOUT


HDM_SETITEM  (preliminaryWindows NT)
HDM_SETITEM  (preliminary−Windows NT)

HDM_SETITEM

wParam = (WPARAM) (int) index;

lParam = (LPARAM) (const HD_ITEM FAR*) phdi;

// Corresponding macro

BOOL Header_SetItem(hwndHD, index, phdi);

The HDM_SETITEM message sets the attributes of the specified item in a header control.

Parameters

hwndHD

Handle to the header control.

index

Index of the item whose attributes are to be changed.

phdi

Pointer to an HD_ITEM structure. When the message is sent, the mask member indicates the attributes to set. The other members specify new attributes.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

The HDN_ITEMCHANGING notification message is sent to the parent window before the item attributes are changed. The parent window can return FALSE to prevent the changes, and in that case, HDM_SETITEM returns FALSE. If the parent window returns TRUE, the changes are made and the parent window receives the HDN_ITEMCHANGED notification message.

See Also

HD_ITEM, HDN_ITEMCHANGED, HDN_ITEMCHANGING


HDN_BEGINTRACK  (preliminaryWindows NT)
HDN_BEGINTRACK  (preliminary−Windows NT)

HDN_BEGINTRACK

phdn = (HD_NOTIFY FAR *) lParam;

The HDN_BEGINTRACK notification message notifies a header control's parent window that the user has begun dragging a divider in the control (that is, the user has pressed the left mouse button while the mouse cursor is on a divider in the header control). This notification message is sent in the form of a WM_NOTIFY message.

Parameters

phdn

Pointer to an HD_NOTIFY structure that contains information about the header control and the item whose divider is to be dragged.

Return Value

Returns FALSE to allow tracking of the divider or TRUE to prevent tracking.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_DIVIDERDBLCLICK  (preliminaryWindows NT)
HDN_DIVIDERDBLCLICK  (preliminary−Windows NT)

HDN_DIVIDERDBLCLICK

phdn = (HD_NOTIFY FAR *) lParam;

The HDN_DIVIDERDBLCLICK notification message notifies a header control's parent window that the user double-clicked the divider area of the control. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

phdn

Pointer to an HD_NOTIFY structure that contains information about the header control and the item whose divider was double-clicked.

Return Value

No return value.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ENDTRACK  (preliminaryWindows NT)
HDN_ENDTRACK  (preliminary−Windows NT)

HDN_ENDTRACK

phdn = (HD_NOTIFY FAR *) lParam;

The HDN_ENDTRACK notification message notifies a header control's parent window that the user has finished dragging a divider. This notification message sent in the form of a WM_NOTIFY message.

Parameters

phdn

Pointer to an HD_NOTIFY structure that contains information about the header control and the item whose divider was dragged.

Return Value

No return value.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ITEMCHANGED  (preliminaryWindows NT)
HDN_ITEMCHANGED  (preliminary−Windows NT)

HDN_ITEMCHANGED

phdr = (HD_NOTIFY FAR *) lParam;

The HDN_ITEMCHANGED notification message notifies a header control's parent window that the attributes of a header item have changed. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

phdr

Pointer to an HD_NOTIFY structure that contains information about the header control, including the attributes that have changed.

Return Value

No return value.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ITEMCHANGING  (preliminaryWindows NT)
HDN_ITEMCHANGING  (preliminary−Windows NT)

HDN_ITEMCHANGING

phdr = (HD_NOTIFY FAR *) lParam;

The HDN_ITEMCHANGING notification message notifies a header control's parent window that the attributes of a header item are about to change. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

phdr

Pointer to an HD_NOTIFY structure that contains information about the header control and the header item, including the attributes that are about to change.

Return Value

Returns FALSE to allow the changes or TRUE to prevent them.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ITEMCLICK  (preliminaryWindows NT)
HDN_ITEMCLICK  (preliminary−Windows NT)

HDN_ITEMCLICK

phdr = (HD_NOTIFY FAR *) lParam;

The HDN_ITEMCLICK notification message notifies a header control's parent window that the user clicked the control. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

phdr

Pointer to an HD_NOTIFY structure that identifies the header control and specifies the index of the header item that was clicked and the mouse button used to click the item. The pitem member is set to NULL.

Return Value

No return value.

Remarks

A header control sends this notification message after the user releases the left mouse button.

See Also

HD_NOTIFY, WM_NOTIFY


HDN_ITEMDBLCLICK  (preliminaryWindows NT)
HDN_ITEMDBLCLICK  (preliminary−Windows NT)

HDN_ITEMDBLCLICK

pnmhdr = (NMHDR FAR *) lParam;

The HDN_ITEMDBLCLICK notification message notifies a header control's parent window that the user double-clicked the control. This notification message is sent in the form of a WM_NOTIFY message. Only header controls that have the HDS_BUTTONS style send this notification.

Parameters

pnmhdr

Pointer to an NMHDR structure that contains the handle and identifier of the header control and the HDN_ITEMDBLCLICK notification code.

Return Value

No return value.

Remarks

A control that has the HDS_DIVIDERTRACK style does not send this notification when the user double-clicks the divider.

See Also

NMHDR, WM_NOTIFY


HDN_TRACK  (preliminaryWindows NT)
HDN_TRACK  (preliminary−Windows NT)

HDN_TRACK

phdr = (HD_NOTIFY FAR *) lParam;

The HDN_TRACK notification message notifies a header control's parent window that the user is dragging a divider in the header control. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

phdr

Pointer to an HD_NOTIFY structure that contains information about the header control and the item whose divider is being dragged.

Return Value

Returns FALSE to continue tracking the divider or TRUE to end tracking.

See Also

HD_NOTIFY, WM_NOTIFY


HKM_GETHOTKEY  (preliminaryWindows NT)
HKM_GETHOTKEY  (preliminary−Windows NT)

HKM_GETHOTKEY

wParam = 0;

lParam = 0;

The HKM_GETHOTKEY message retrieves the virtual-key code and modifier flags of a hot key from a hot-key control.

Return Value

Returns the virtual-key code and modifier flags. The virtual-key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the following values:

Value	Meaning
HOTKEYF_ALT	ALT key
HOTKEYF_CONTROL	CTRL key
HOTKEYF_EXT	Extended key
HOTKEYF_SHIFT	SHIFT key
Remarks

The 16-bit value returned by this message can be used as the wParam parameter in the WM_SETHOTKEY message.

See Also

WM_SETHOTKEY


HKM_SETHOTKEY  (preliminaryWindows NT)
HKM_SETHOTKEY  (preliminary−Windows NT)

HKM_SETHOTKEY

wParam = MAKEWORD(bVKHotKey, bfMods);

lParam = 0;

The HKM_SETHOTKEY message sets the hot key combination for a hot-key control.

Parameters

bVKHotKey

Virtual-key code of the hot key.

bfMods

Modifier flags indicating the keys that, when used in combination with bVKHotKey, define a hot-key combination. For a list of modifier flag values, see the description of the HKM_GETHOTKEY message.

Return Value

No return value.

See Also

HKM_GETHOTKEY


HKM_SETRULES  (preliminaryWindows NT)
HKM_SETRULES  (preliminary−Windows NT)

HKM_SETRULES

wParam = (WPARAM) fwCombInv;

lParam = MAKELPARAM(fwModInv, 0);

The HKM_SETRULES message defines the invalid combinations and the default modifier combination for a hot-key control.

Parameters

fwCombInv

Array of flags that specify invalid key combinations. This parameter can be a combination of the following values:

Value	Meaning
HKCOMB_A	ALT
HKCOMB_C	CTRL
HKCOMB_CA	CTRL+ALT
HKCOMB_NONE	Unmodified keys
HKCOMB_S	SHIFT
HKCOMB_SA	SHIFT+ALT
HKCOMB_SC	SHIFT+CTRL
HKCOMB_SCA	SHIFT+CTRL+ALT
fwModInv

Array of flags that specify the key combination to use when the user enters an invalid combination. For a list of modifier flag values, see the description of the HKM_GETHOTKEY message.

Return Value

No return value.

Remarks

When a user enters an invalid key combination, as defined by flags specified in fwCombInv, the system uses the bitwise-OR operator to combine the keys entered by the user with the flags specified in fwModInv. The resulting key combination is converted into a string and then displayed in the hot-key control.

See Also

HKM_GETHOTKEY


IMC_CLOSESTATUSWINDOW

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_CLOSESTATUSWINDOW;
lParam = (LPARAM) 0;

An application sends the IMC_CLOSESTATUSWINDOW message to the IME window to hide the status window.

Return Value

Returns zero if successful, non-zero otherwise.

Remarks

When the status window of IME is already hidden, this message does nothing. Although an application may send this message to the IME window, the application does not receive the corresponding IMN_CLOSESTATUSWINDOW message.


IMC_GETCANDIDATEPOS  (preliminaryWindows 95)
IMC_GETCANDIDATEPOS  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCANDIDATEPOS;
lParam = (LPARAM) &CandForm;

An application sends the IMC_GETCANDIDATEPOS message to an IME window to get the position of the candidate window. Because the IME may adjust the position of a candidate window, an application uses this message to get the actual position to decide whether to reposition the window.

Parameters

lParam

Pointer to the CANDIDATEFORM structure that receives the position of the candidate window.

Return Value

Returns zero if successful, nonzero otherwise.

Remarks

The returned position is in window coordinates relative to the window having the current input focus.

See Also

CANDIDATEFORM


IMC_GETCOMPOSITIONFONT  (preliminaryWindows 95)
IMC_GETCOMPOSITIONFONT  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCOMPOSITIONFONT;
lParam = (LPARAM) &LogFont;

An application sends the IMC_GETCOMPOSITIONFONT message to an IME window to retrieve the logical font used for displaying intermediate characters in the composition window.

Parameters

lParam

Pointer to the LOGFONT structure that receives information about the logical font.

Return Value

Returns zero if successful, nonzero otherwise.

See Also

LOGFONT


IMC_GETCOMPOSITIONWINDOW  (preliminaryWindows 95)
IMC_GETCOMPOSITIONWINDOW  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCOMPOSITIONWINDOW;
lParam = (LPARAM) &CompForm;

An application sends the IMC_GETCOMPOSITIONWINDOW message to an IME window to get the position of the composition window. Because the IME may adjust the position of a composition window, an application uses this message to get the actual position to decide whether to reposition the window.

Parameters

lParam

Pointer to the COMPOSITIONFORM structure that receives the position of the composition window.

Return Value

Returns zero if successful, nonzero otherwise.

Remarks

The returned position is in window coordinates relative to the window having the current input focus.

See Also

COMPOSITIONFORM


IMC_GETCONVERSIONMODE  (preliminaryWindows 95)
IMC_GETCONVERSIONMODE  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETCONVERSIONMODE;
lParam = 0;

An application sends the IMC_GETCONVERSIONMODE message to an IME window to obtain the current conversion mode. The window retrieves the current conversion mode from the current input context.

Return Value

Returns a combination of the values given in the "IME Conversion Modes" table in Input Method Editor Constants.


IMC_GETOPENSTATUS  (preliminaryWindows 95)
IMC_GETOPENSTATUS  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETOPENSTATUS;
lParam = 0;

An application sends the IMC_GETOPENSTATUS message to an IME window to determine whether the IME is open.

Return Value

Returns nonzero if the current IME is open, 0 otherwise.


IMC_GETSENTENCEMODE  (preliminaryWindows 95)
IMC_GETSENTENCEMODE  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETSENTENCEMODE;
lParam = 0;

An application sends the IMC_GETSENTENCEMODE message to an IME window to obtain current sentence mode.

Return Value

Returns a combination of the values given in the "IME Sentence Modes" table in Input Method Editor Constants.


IMC_GETSTATUSWINDOWPOS  (preliminaryWindows 95)
IMC_GETSTATUSWINDOWPOS  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_GETSTATUSWINDOWPOS;
lParam = 0;

An application sends the IMC_GETSTATUSWINDOWPOS message to an IME window to get the position of the status window.

Return Value

Returns a POINTS structure that contains the x- and y-coordinates of the status window position.

See Also

POINTS


IMC_OPENSTATUSWINDOW

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_OPENSTATUSWINDOW;
lParam = (LPARAM) 0;

An application sends the IMC_OPENSTATUSWINDOW message to the IME window to show the status window. This message is ignored if the system is not in the show IME status mode. The user can set or clear the show IME status mode from the task bar.

Return Value

Returns zero if successful, non-zero otherwise.

Remarks

If the status window is already shown, this message does nothing. Although the application may send this message to the IME window, the application does not receive the corresponding IMN_OPENSTATUSWINDOW message.


IMC_SETCANDIDATEPOS  (preliminaryWindows 95)
IMC_SETCANDIDATEPOS  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCANDIDATEPOS;
lParam = (LPARAM) &CandForm;

An application sends the IMC_SETCANDIDATEPOS message to an IME window to set the position of the candidate window. This message is intended for applications that display composition characters on their own but use the IME window to display candidates.

Parameters

lParam

Pointer to the CANDIDATEFORM structure that contains the x- and y-coordinates for the candidate window. The application should set the dwIndex member in the structure.

Return Value

Return zero if successful, nonzero otherwise.

See Also

CANDIDATEFORM


IMC_SETCOMPOSITIONFONT  (preliminaryWindows 95)
IMC_SETCOMPOSITIONFONT  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCOMPOSITIONFONT;
lParam = (LPARAM) &LogFont;

An application sends the IMC_SETCOMPOSITIONFONT message to an IME window to specify the logical font to use for displaying intermediate characters in the composition window.

Parameters

lParam

Pointer to the LOGFONT structure that contains information about the logical font.

Return Value

Returns zero if successful, nonzero otherwise.

Remarks

When processing this message, the IME window changes the current selected font in the input context.

See Also

LOGFONT


IMC_SETCOMPOSITIONWINDOW  (preliminaryWindows 95)
IMC_SETCOMPOSITIONWINDOW  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCOMPOSITIONWINDOW;
lParam = (LPARAM) &CompForm;

An application sends the IMC_SETCOMPOSITIONWINDOW message to an IME window to set the style of the composition window. The message set this style in the current input context and the style is subsequently applied to each IME window that receives that input context.

Parameters

lParam

Pointer to the COMPOSITIONFORM structure that contains the style information.

Return Value

Returns zero if successful, nonzero otherwise.

Remarks

By default, the IME window has the CFS_POINT style. This means the IME window uses the current caret position and window client area when it opens composition window.

See Also

COMPOSITIONFORM


IMC_SETCONVERSIONMODE  (preliminaryWindows 95)
IMC_SETCONVERSIONMODE  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETCONVERSIONMODE;
lParam = (LPARAM) cMode;

An application sends the IMC_SETCONVERSIONMODE message to an IME window to set current conversion mode.

Parameters

lParam

Conversion mode. Can be one of the values given in the "IME Conversion Modes" table in Input Method Editor Constants.

Return Value

Returns zero if successful, nonzero otherwise.


IMC_SETOPENSTATUS  (preliminaryWindows 95)
IMC_SETOPENSTATUS  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETOPENSTATUS;
lParam = (LPARAM) bOpen;

An application sends the IMC_SETOPENSTATUS message to an IME window to open or close the current IME.

Parameters

lParam

Open status. If TRUE, the IME is opened, closed otherwise.

Return Value

Returns zero if successful, nonzero otherwise.

Remarks

When processing this message, the IME window changes the current input context.


IMC_SETSENTENCEMODE  (preliminaryWindows 95)
IMC_SETSENTENCEMODE  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETSENTENCEMODE;
lParam = 0;

An application sends the IMC_SETSENTENCEMODE message to an IME window to set the current sentence mode.

Parameters

lParam

Sentence mode. Can be one of the values given in the "IME Sentence Modes" table in Input Method Editor Constants.

Return Value

Returns zero if successful, nonzero otherwise.


IMC_SETSTATUSWINDOWPOS  (preliminaryWindows 95)
IMC_SETSTATUSWINDOWPOS  (preliminary−Windows 95)

msg = (UINT) WM_IME_CONTROL;
wParam = (WPARAM) IMC_SETSTATUSWINDOWPOS;
lParam = (LPARAM) &pts;

An application sends the IMC_SETSTATUSWINDOWPOS message to an IME window to set the position of the status window.

Parameters

lParam

Pointer to a POINTS structure that contains the x- and y-coordinates of the position of the status window.

Return Value

Returns zero if successful, nonzero otherwise.

See Also

POINTS


IMN_CHANGECANDIDATE  (preliminaryWindows 95)
IMN_CHANGECANDIDATE  (preliminary−Windows 95)

fCandidates = (DWORD) lParam;

The IMN_CHANGECANDIDATE message is sent to the application when an IME is about to change the content of the candidate window. An application should process this notification message if it displays candidates itself. The application receives this notification message through the WM_IME_NOTIFY message.

Parameters

fCandidates

Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be changed.

Return Value

No return value.

Remarks

The IME window changes the appearance of the candidate window when it processes this message. An application can get information about the system window with the ImmGetCandidateListCount and ImmGetCandidateList functions.

See Also

ImmGetCandidateList, ImmGetCandidateListCount, WM_IME_NOTIFY


IMN_CLOSECANDIDATE  (preliminaryWindows 95)
IMN_CLOSECANDIDATE  (preliminary−Windows 95)

fCandidate = (DWORD) lParam;

The IMN_CLOSECANDIDATE message is sent to the application when an IME is about to close the candidate window. An application should process this message if it displays candidates itself. The application receives this notification message through the WM_IME_NOTIFY message.

Parameters

fCandidates

Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be closed.

Return Value

No return value.

Remarks

By default, the IME window destroys a candidate window when it processes this message.

See Also

WM_IME_NOTIFY


IMN_CLOSESTATUSWINDOW(preliminaryWindows 95)
IMN_CLOSESTATUSWINDOW  (preliminary−Windows 95)

The IMN_CLOSESTATUSWINDOW message is sent to the application when an IME is about to close the status window. An application should process this notification message if it displays the status window for the IME. The application receives this notification message through the WM_IME_NOTIFY message.

Return Value

No return value.

Remarks

The IME window closes the status window when it processes this message.

See Also

WM_IME_NOTIFY


IMN_GUIDELINE(preliminaryWindows 95)
IMN_GUIDELINE  (preliminary−Windows 95)

The IMN_GUIDELINE message is sent when an IME is about to show an error message or other information. An application processes this message by calling the ImmGetGuideLine function to retrieve the error message or information from the IME. The application receives this notification message through the WM_IME_NOTIFY message.

Return Value

No return value.

Remarks

The IME window displays the error message or information string in an information window.

See Also

ImmGetGuideLine, WM_IME_NOTIFY


IMN_OPENCANDIDATE  (preliminaryWindows 95)
IMN_OPENCANDIDATE  (preliminary−Windows 95)

fCandidate = (DWORD) lParam;

The IMN_OPENCANDIDATE message is sent to the application when an IME is about to open the candidate window. An application should process this message if it displays candidates itself. The application can retrieve a list of candidates to display by using the ImmGetCandidateList function. The application receives this notification message through the WM_IME_NOTIFY message.

Parameters

fCandidates

Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be opened.

Return Value

No return value.

Remarks

By default, the IME window creates a candidate window when it processes this message.

See Also

ImmGetCandidateList, WM_IME_NOTIFY


IMN_OPENSTATUSWINDOW(preliminaryWindows 95)
IMN_OPENSTATUSWINDOW  (preliminary−Windows 95)

The IMN_OPENSTATUSWINDOW message is sent when an IME is about to create the status window. An application processes this message to display the status window for the IME by itself. The application receives this notification message through the WM_IME_NOTIFY message.

Return Value

No return value.

Remarks

The IME window creates a status window when it processes this message and sets the strings to display in the window into the input context. Applications can get information about the status window by using the ImmGetConversionStatus function.

See Also

ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETCANDIDATEPOS  (preliminaryWindows 95)
IMN_SETCANDIDATEPOS  (preliminary−Windows 95)

fCandidates = (DWORD) lParam;

The IMN_SETCANDIDATEPOS message is sent when the IME is about to move the candidate window. An application should process this message if it displays the candidate window itself. The application receives this notification message through the WM_IME_NOTIFY message.

Parameters

fCandidates

Candidate lists flag. Each bit corresponds to a candidate list: bit 0 to the first list, bit 1 to the second, and so on. If a specified bit is 1, the corresponding candidate window is about to be moved.

Return Value

No return value.

Remarks

The IME window moves the candidate window when it processes this message.

See Also

WM_IME_NOTIFY


IMN_SETCOMPOSITIONFONT(preliminaryWindows 95)
IMN_SETCOMPOSITIONFONT  (preliminary−Windows 95)

The IMN_SETCOMPOSITIONFONT message is sent when the font of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Value

No return value.

Remarks

The application can get information about the font by using the ImmGetCompositionFont function. The IME window subsequently uses the font to draw the composition string.

See Also

ImmGetCompositionFont, WM_IME_NOTIFY


IMN_SETCOMPOSITIONWINDOW(preliminaryWindows 95)
IMN_SETCOMPOSITIONWINDOW  (preliminary−Windows 95)

The IMN_SETCOMPOSITIONWINDOW message is sent when the style or position of the composition window is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Value

No return value.

Remarks

The application can get information about the composition form by using the IMC_GETCOMPOSITIONWINDOW message.

See Also

IMC_GETCOMPOSITIONWINDOW, WM_IME_NOTIFY


IMN_SETCONVERSIONMODE(preliminaryWindows 95)
IMN_SETCONVERSIONMODE  (preliminary−Windows 95)

The IMN_SETCONVERSIONMODE message is sent when the conversion mode of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Value

No return value.

Remarks

The application can get information about the conversion mode by using the ImmGetConversionStatus function.

See Also

ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETOPENSTATUS(preliminaryWindows 95)
IMN_SETOPENSTATUS  (preliminary−Windows 95)

The IMN_SETOPENSTATUS message is sent when the open status of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Value

No return value.

Remarks

The application can get information about the open status by using the ImmGetOpenStatus function.

See Also

ImmGetOpenStatus, WM_IME_NOTIFY


IMN_SETSENTENCEMODE(preliminaryWindows 95)
IMN_SETSENTENCEMODE  (preliminary−Windows 95)

The IMN_SETSENTENCEMODE message is sent when the sentence mode of the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Value

No return value.

Remarks

The application can get information about the sentence mode by using the ImmGetConversionStatus function.

See Also

ImmGetConversionStatus, WM_IME_NOTIFY


IMN_SETSTATUSWINDOWPOS(preliminaryWindows 95)
IMN_SETSTATUSWINDOWPOS  (preliminary−Windows 95)

The IMN_SETSTATUSWINDOWPOS message is sent when the status window position in the input context is updated. The application receives this notification message through the WM_IME_NOTIFY message.

Return Value

No return value.

Remarks

The application can get information about the status window position by using the IMC_GETSTATUSWINDOWPOS message.

See Also

IMC_GETSTATUSWINDOWPOS, WM_IME_NOTIFY


LB_ADDFILE

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.

Parameters

lpszFilename

Value of lParam. Points to the name of the file to add.

Return Value

The return value is the zero-based index of the file that was added, or LB_ERR if an error occurs.

Remarks

The list box to which lpszFilename is added must have been filled by the DlgDirList function.

See Also

DlgDirList, LB_ADDSTRING


LB_ADDSTRING

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.

Parameters

lpsz

Value of lParam. Points to the null-terminated string that is to be added.

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the value of the lpsz parameter is stored as item data instead of the string it would otherwise point to. You can send the LB_GETITEMDATA and LB_SETITEMDATA messages to retrieve or modify the item data.

Return Value

The return value is the zero-based index of the string in the list box. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new string, the return value is LB_ERRSPACE.

Remarks

If you create an owner-drawn list box with the LBS_SORT style but not the LBS_HASSTRINGS style, the system sends the WM_COMPAREITEM message one or more times to the owner of the list box to place the new item properly in the list box.

See Also

LB_DELETESTRING, LB_INSERTSTRING, LB_SELECTSTRING, WM_COMPAREITEM


LB_DELETESTRING

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the string to be deleted.

Return Value

The return value is a count of the strings remaining in the list. The return value is LB_ERR if the index parameter specifies an index greater than the number of items in the list.

Remarks

If an application creates the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the system sends a WM_DELETEITEM message to the owner of the list box so the application can free any additional data associated with the item.

See Also

LB_ADDSTRING, LB_INSERTSTRING, WM_DELETEITEM


LB_DIR

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.

Parameters

uAttrs

Value of wParam. Specifies the attributes of the files to be added to the list box. This parameter can be a combination of the following values:

Value	Description
DDL_ARCHIVE	Includes archived files.
DDL_DIRECTORY	Includes subdirectories. Subdirectory names are enclosed in square brackets ([ ]).
DDL_DRIVES	Includes drives. Drives are listed in the form [-x-], where x is the drive letter.
DDL_EXCLUSIVE	Includes only files with the specified attributes. By default, read-write files are listed even if DDL_READWRITE is not specified.
DDL_HIDDEN	Includes hidden files.
DDL_READONLY	Includes read-only files.
DDL_READWRITE	Includes read-write files with no additional attributes.
DDL_SYSTEM	Includes system files.
lpszFileSpec

Value of lParam. Points to the null-terminated string that specifies the filename to add to the list. If the filename contains wildcards (for example, *.*), all files that match the wildcards and have the attributes specified by the uAttrs parameter are added to the list.

Return Value

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

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.

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is −1, the entire list box is searched from the beginning.

lpszFind

Value of lParam. Points to the null-terminated string that contains the prefix to search for. The search is case independent, so this string can contain any combination of uppercase and lowercase letters.

Return Value

The return value is the index of the matching item, or LB_ERR if the search was unsuccessful.

Remarks

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, this message returns the index of the item with a long value (supplied as the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message) that matches the value supplied as the lpszFind parameter.

See Also

LB_ADDSTRING, LB_INSERTSTRING, LB_SELECTSTRING


LB_FINDSTRINGEXACT

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.

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is  − 1, the entire list box is searched from the beginning.

lpszFind

Value of lParam. Points to the null-terminated string to search for. This string can contain a complete filename, including the extension. The search is not case sensitive, so this string can contain any combination of uppercase and lowercase letters.

Return Value

The return value is the zero-based index of the matching item, or LB_ERR if the search was unsuccessful.

Remarks

If an application creates the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the action taken by LB_FINDSTRINGEXACT depends on whether the LBS_SORT style is used. If LBS_SORT is used, the system sends WM_COMPAREITEM messages to the list box owner to determine which item matches the specified string. Otherwise, LB_FINDSTRINGEXACT attempts to match the 32-bit value against the value of the lpszFind parameter.

See Also

LB_FINDSTRING, LB_SELECTSTRING, WM_COMPAREITEM


LB_GETANCHORINDEX

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—that is, the item from which a multiple selection starts. A multiple selection spans all items from the anchor item to the caret item.

Parameters

This message has no parameters.

Return Value

The return value is the index of the anchor item.

See Also

LB_SETANCHORINDEX


LB_GETCARETINDEX

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.

Return Value

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

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.

Return Value

The return value is the number of items in the list box, or LB_ERR if an error occurs.

Remarks

The returned count is one greater than the index value of the last item (the index is zero-based).

See Also

LB_SETCOUNT


LB_GETCURSEL

LB_GETCURSEL

wParam = 0;     // not used; must be zero

lParam = 0;     // not used; must be zero

Send an LB_GETCURSEL message to retrieve the index of the currently selected item, if any, in a single-selection list box. For a multiple selection list box, the message retrieves the index of the first selected item (the base item), if any.

Parameters

This message has no parameters.

Return Value

The return value is the zero-based index of the currently selected item or of the base item in a multiple selection.

If there is no selection, the return value is LB_ERR.

Remarks

Use the LB_GETCARETINDEX message to retrieve the index of the item that has the focus rectangle in a multiple-selection list box.

See Also

LB_GETCARETINDEX, LB_SETCURSEL


LB_GETHORIZONTALEXTENT

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.

Return Value

The return value is the scrollable width, in pixels, of the list box.

Remarks

To respond to the LB_GETHORIZONTALEXTENT message, the list box must have been defined with the WS_HSCROLL style.

See Also

LB_SETHORIZONTALEXTENT


LB_GETITEMDATA

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.

Parameters

index

Value of wParam. Specifies the index of the item.

Return Value

The return value is the 32-bit value associated with the item, or LB_ERR if an error occurs. If the item is in an owner-drawn list box and was created without the LBS_HASSTRINGS style, this 32-bit value was in the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message that added the item to the list box. Otherwise, it is the value in the lParam of an LB_SETITEMDATA message.

See Also

LB_ADDSTRING, LB_INSERTSTRING, LB_SETITEMDATA


LB_GETITEMHEIGHT

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the list box item. This index is used only if the list box has the LBS_OWNERDRAWVARIABLE style; otherwise, it must be  zero.

Return Value

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

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.

Parameters

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.

Return Value

If an error occurs, the return value is LB_ERR.

See Also

RECT


LB_GETLOCALE

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.

Return Value

The return value is a 32-bit value that specifies the current locale of the list box. The high-order word contains the country code and the low-order word contains the language identifier.

Remarks

The language identifier consists of a sublanguage identifier and a primary language identifier. Use the PRIMARYLANGID macro to extract the primary language identifier from the low-order word of the return value, and the SUBLANGID macro to extract the sublanguage identifier.

See Also

LB_ADDSTRING, LB_SETLOCALE, PRIMARYLANGID, SUBLANGID


LB_GETSEL

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the item.

Return Value

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

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.

Return Value

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

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.

Parameters

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.

Return Value

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

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.

Parameters

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.

Return Value

The return value is the length of the string, in characters, excluding the terminating null character. If index does not specify a valid index, the return value is LB_ERR.

Remarks

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the buffer pointed to by the lpszBuffer parameter will receive the 32-bit value associated with the item (the item data).

See Also

LB_GETTEXTLEN


LB_GETTEXTLEN

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the string.

Return Value

The return value is the length of the string, in characters, excluding the terminating null character. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

If the index parameter does not specify a valid index, the return value is LB_ERR.

Remarks

Under certain conditions, the return value is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the operating system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

CB_GETLBTEXT, GetWindowText, LB_GETTEXT, WM_GETTEXT


LB_GETTOPINDEX

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.

Return Value

The return value is the index of the first visible item in the list box.

See Also

LB_SETTOPINDEX


LB_INITSTORAGE  (preliminaryWindows 95)
LB_INITSTORAGE  [image]  (preliminary−Windows 95)

LB_INITSTORAGE

wParam = (WPARAM) (int) cItems;  // number of items to add

lParam = (LPARAM) (DWORD) cb;   // amount of memory to allocate, in bytes

Allocates memory for storing list box items. An application sends this message before adding a large number of items to a list box.

Parameters

cItems

Specifies the number of items to add.

cb

Specifies the amount of memory, in bytes, to allocate for item strings.

Return Value

The return value is the maximum number of items that the memory object can store before another memory reallocation is needed, if successful. It is LB_ERRSPACE if not enough memory is available.

Remarks

This message helps speed up the initialization of list boxes that have a large number of items (more than 100). It preallocates the specified amount of memory so that subsequent LB_ADDSTRING, LB_INSERTSTRING, LB_DIR, and LB_ADDFILE messages take the shortest possible time. You can use estimates for the cItems and cb parameters. If you overestimate, some extra memory is allocated; if you underestimate, the normal allocation is used for items that exceed the preallocated amount.

See Also

LB_ADDFILE, LB_ADDSTRING, LB_DIR, LB_INSERTSTRING


LB_INSERTSTRING

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the position at which to insert the string. If this parameter is −1, the string is added to the end of the list.

lpsz

Value of lParam. Points to the null-terminated string to be inserted.

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the value of the lpsz parameter is stored as item data instead of the string it would otherwise point to. You can send the LB_GETITEMDATA and LB_SETITEMDATA messages to retrieve or modify the item data.

Return Value

The return value is the index of the position at which the string was inserted. If an error occurs, the return value is LB_ERR. If there is insufficient space to store the new string, the return value is LB_ERRSPACE.

See Also

LB_ADDSTRING, LB_SELECTSTRING


LB_ITEMFROMPOINT  (preliminaryWindows 95)
LB_ITEMFROMPOINT  [image]  (preliminary−Windows 95)

LB_ITEMFROMPOINT

wParam = 0;                                // not used, must be zero

lParam = (LPARAM) MAKELPARAM(xPos, yPos);  // coordinates of point

An application sends this message to retrieve the zero-based index of the item nearest the specified point in a list box.

Parameters

xPos

Value of the low-order word of lParam. Specifies the x-coordinate of a point, relative to the upper-left corner of the client area of the list box.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of a point, relative to the upper-left corner of the client area of the list box.

Return Value

The return value contains the index of the nearest item in the low-order word. The high-order word is zero if the specified point is in the client area of the list box, or one if it is outside the client area.


LB_RESETCONTENT

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.

Return Value

This message does not return a value.

Remarks

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, the owner of the list box receives a WM_DELETEITEM message for each item in the list box.

See Also

WM_DELETEITEM


LB_SELECTSTRING

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.

Parameters

indexStart

Value of wParam. Specifies the zero-based index of the item before the first item to be searched. When the search reaches the bottom of the list box, it continues from the top of the list box back to the item specified by the indexStart parameter. If indexStart is −1, the entire list box is searched from the beginning.

lpszFind

Value of lParam. Points to the null-terminated string that contains the prefix to search for. The search is case independent, so this string can contain any combination of uppercase and lowercase letters.

Return Value

If the search is successful, the return value is the index of the selected item. If the search is unsuccessful, the return value is LB_ERR and the current selection is not changed.

Remarks

The list box is scrolled, if necessary, to bring the selected item into view.

Do not use this message with a list box that has the LBS_MULTIPLESEL style.

An item is selected only if its initial characters from the starting point match the characters in the string specified by the lpszFind parameter.

If you create the list box with an owner-drawn style but without the LBS_HASSTRINGS style, this message returns the index of the item whose long value (supplied as the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message) matches the value supplied as the lParam parameter of LB_SELECTSTRING.

See Also

LB_ADDSTRING, LB_FINDSTRING, LB_INSERTSTRING


LB_SELITEMRANGE

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.

Parameters

fSelect

Value of wParam. Specifies how to set the selection. If the fSelect parameter is TRUE, the string is selected and highlighted; if fSelect is zero, the highlight is removed and the string is no longer selected.

wFirst

Value of the low-order word of lParam. Specifies the zero-based index of the first item to select.

wLast

Value of the high-order word of lParam. Specifies the zero-based index of the last item to select.

Return Value

If an error occurs, the return value is LB_ERR.

Remarks

Use this message only with multiple-selection list boxes.

This message can select a range only within the first 65,536 items.

See Also

LB_SELITEMRANGEEX, LB_SETSEL


LB_SELITEMRANGEEX

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.

Parameters

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.

Return Value

If an error occurs, the return value is LB_ERR.

Remarks

If the wFirst parameter is less than the wLast parameter, the specified range of items is selected. If wFirst is greater than wLast, the selection is removed from the specified range of items.

Use this message only with multiple-selection list boxes.

This message can select a range only within the first 65,536 items.

See Also

LB_SELITEMRANGE, LB_SETSEL


LB_SETANCHORINDEX

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 anchor item—that is, the item from which a multiple selection starts. A multiple selection spans all items from the anchor item to the caret item.

Parameters

index

Value of wParam. Specifies the index of the new anchor item.

Return Value

If the message succeeds, the return value is zero.

If the message fails, the return value is LB_ERR.

See Also

LB_GETANCHORINDEX


LB_SETCARETINDEX

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.

Parameters

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 it is TRUE, the item is scrolled until it is at least partially visible.

Return Value

If an error occurs, the return value is LB_ERR.

See Also

LB_GETCARETINDEX


WM_CONTEXTMENU  (preliminaryWindows NT)
WM_CONTEXTMENU  [image]  (preliminary−Windows NT)

hwnd = (HWND) wParam;

xPos = LOWORD(lParam);

yPos = HIWORD(lParam);

The WM_CONTEXTMENU message notifies a window that the user clicked the right mouse button (right clicked) in the window.

Parameters

hwnd

Handle to the window in which the user right clicked the mouse. This can be a child window of the window receiving the message. For more information about processing this message, see the Remarks section.

xPos

Horizontal position of the cursor, in screen coordinates, at the time of the mouse click.

yPos

Vertical position of the cursor, in screen coordinates, at the time of the mouse click.

Return Value

No return value.

Remarks

A window can process this message by displaying a context menu using the TrackPopupMenu or TrackPopupMenuEx function.

If a window does not display a context menu it should pass this message to the DefWindowProc function. If a window is a child window, DefWindowProc sends the message to the parent. Otherwise, DefWindowProc displays a default context menu if the specified position is in the window's caption.

DefWindowProc generates the WM_CONTEXTMENU message when it processes the WM_RBUTTONUP or WM_NCRBUTTONUP message.

See Also

DefWindowProc, TrackPopupMenu, TrackPopupMenuEx, WM_NCRBUTTONUP, WM_RBUTTONUP


WM_COPY

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.

Return Value

This message does not return a value.

Remarks

When sent to a combo box, the WM_COPY message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

WM_CLEAR, WM_CUT, WM_PASTE


WM_COPYDATA

WM_COPYDATA

wParam = (WPARAM) (HWND) hwnd;            // 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.

Parameters

hwnd

Identifies the window passing the data.

pcds

Points to a COPYDATASTRUCT structure that contains the data to be passed.

Return Value

If the receiving application processes this message, it should return TRUE; otherwise, it should return FALSE.

Remarks

An application must use the SendMessage function to send this message, not the PostMessage function.

The data being passed must not contain pointers or other references to objects not accessible to the application receiving the data.

While this message is being sent, the referenced data must not be changed by another thread of the sending process.

The receiving application should consider the data read-only. The pcds parameter is valid only during the processing of the message. The receiving application should not free the memory referenced by pcds. If the receiving application must access the data after SendMessage returns, it must copy the data into a local buffer.

See Also

PostMessage, SendMessage, COPYDATASTRUCT


WM_CPL_LAUNCH

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.

Parameters

hwnd

Value of wParam. Specifies the handle of the window sending the message. The WM_CPL_LAUNCHED message is sent to this window.

lpszAppName

Value of lParam. Specifies a far pointer to a string containing the name of the Control Panel application to open.

Return Value

If the application starts, the return value is TRUE; otherwise, it is FALSE.

See Also

WM_CPL_LAUNCHED


WM_CPL_LAUNCHED

WM_CPL_LAUNCHED

fAppStarted = (BOOL) wParam;

The WM_CPL_LAUNCHED message is sent when a Control Panel application, started by the WM_CPL_LAUNCH message, has closed. The WM_CPL_LAUNCHED message is sent to the window identified by the wParam parameter of the WM_CPL_LAUNCH message that started the application.

Parameters

fAppStarted

Value of wParam. Specifies whether the application was started. If the application was started, this parameter is TRUE; otherwise, it is FALSE.

Return Value

The value returned by the application is ignored for this message.

See Also

WM_CPL_LAUNCH


WM_CREATE

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.

Parameters

lParam

Value of lParam. Points to a CREATESTRUCT structure that contains information about the window being created. The members of CREATESTRUCT are identical to the parameters of the CreateWindowEx function.

Return Value

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

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.

Parameters

hdcButton

Value of wParam. Identifies the display context for the button.

hwndButton

Value of lParam. Identifies the button.

Return Value

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the button.

Default Action

The DefWindowProc function selects the default system colors for the button.

Remarks

The WM_CTLCOLORBTN message is never sent between threads. It is sent only within one thread.

The text color of a check box or radio button applies to the box or button, its check mark, and the text. The focus rectangle for these buttons remains the system default color (typically black). The text color of a group box applies to the text but not to the line that defines the box. The text color of a push button applies only to its focus rectangle; it does not affect the color of the text.

You cannot use a custom palette to set a button's text or background color. Although the SelectPalette and RealizePalette functions will succeed, they will have no effect on the button.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORDLG

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.

Parameters

hdcDlg

Value of wParam. Identifies the device context for the dialog box.

hwndDlg

Value of lParam. Identifies the dialog box.

Return Value

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the dialog box.

Default Action

The DefWindowProc function selects the default system colors for the dialog box.

Remarks

The WM_CTLCOLORDLG message is never sent between threads. It is sent only within one thread.

Note that the WM_CTLCOLORDLG message is sent to the dialog box itself; all of the other WM_CTLCOLOR* messages are sent to the owner of the control.

You cannot use a custom palette to draw a dialog box's text and background colors. Although you could select and realize a custom palette into the dialog box's display context while handling the WM_CTLCOLORDLG message, no message is sent when dialog box drawing is done, and thus you wouldn't know when to restore the display context's previous palette.

You cannot use a custom palette to set a dialog box's text or background color. Although the SelectPalette and RealizePalette functions will succeed, they will have no effect on the dialog box.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLOREDIT

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.

Parameters

hdcEdit

Value of wParam. Identifies the device context for the edit control window.

hwndEdit

Value of lParam. Identifies the edit control.

Return Value

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the edit control.

Default Action

The DefWindowProc function selects the default system colors for the edit control.

Remarks

The WM_CTLCOLOREDIT message is never sent between threads, it is only sent within the same thread.

You cannot use a custom palette to set an edit control's text or background color. Although the SelectPalette and RealizePalette functions will succeed, they will have no effect on the edit control.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORLISTBOX

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.

Parameters

hdcLB

Value of wParam. Identifies the device context for the list box.

hwndLB

Value of lParam. Identifies the list box.

Return Value

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the list box.

Default Action

The DefWindowProc function selects the default system colors for the list box.

Remarks

The WM_CTLCOLORLISTBOX message is never sent between threads. It is sent only within one thread.

You cannot use a custom palette to set a list box's text or background color. Although the SelectPalette and RealizePalette functions will succeed, they will have no effect on the list box.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORMSGBOX

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.

Parameters

hdcMB

Value of wParam. Identifies the device context for the message box.

hwndMB

Value of lParam. Identifies the message box.

Return Value

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the message box.

Default Action

The DefWindowProc function selects the default system colors for the message box.

Remarks

The WM_CTLCOLORMSGBOX message is never sent between threads. It is sent only within one thread.

You cannot use a custom palette to set a message box's text or background color. Although the SelectPalette and RealizePalette functions will succeed, they will have no effect on the message box.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORSCROLLBAR, WM_CTLCOLORSTATIC


WM_CTLCOLORSCROLLBAR

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.

Parameters

hdcSB

Value of wParam. Identifies the device context for the scroll bar control.

hwndSB

Value of lParam. Identifies the scroll bar.

Return Value

If an application processes this message, it must return the handle of a brush. Windows uses the brush to paint the background of the scroll bar control.

Default Action

The DefWindowProc function selects the default system colors for the scroll bar control.

Remarks

The WM_CTLCOLORSCROLLBAR message is never sent between threads; it is only sent within the same thread.

You cannot use a custom palette to set a scroll bar's text or background color. Although the SelectPalette and RealizePalette functions will succeed, they will have no effect on the scroll bar.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSTATIC


WM_CTLCOLORSTATIC

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 handle to set the text and background colors of the static control.

Parameters

hdcStatic

Value of wParam. Identifies the device context for the static control window.

hwndStatic

Value of lParam. Identifies the static control.

Return Value

If an application processes this message, the return value is the handle of a brush that Windows uses to paint the background of the static control.

Default Action

The DefWindowProc function selects the default system colors for the static control.

Remarks

The WM_CTLCOLORSTATIC message is never sent between threads; it is sent only within the same thread.

You cannot use a custom palette to set a static control's text or background color. Although the SelectPalette and RealizePalette functions will succeed, they will have no effect on the static control.

See Also

DefWindowProc, RealizePalette, SelectPalette, WM_CTLCOLORBTN, WM_CTLCOLORDLG, WM_CTLCOLOREDIT, WM_CTLCOLORLISTBOX, WM_CTLCOLORMSGBOX, WM_CTLCOLORSCROLLBAR


WM_CUT

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.

Return Value

This message does not return a value.

Remarks

The deletion performed by the WM_CUT message can be undone by sending the edit control an EM_UNDO message.

To delete the current selection without placing the deleted text on the clipboard, use the WM_CLEAR message.

When sent to a combo box, the WM_CUT message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

WM_CLEAR, WM_COPY, WM_PASTE


WM_DDE_ACK

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 DDE application of the receipt and processing of a WM_DDE_POKE, WM_DDE_EXECUTE, WM_DDE_DATA, WM_DDE_ADVISE, WM_DDE_UNADVISE, or WM_DDE_INITIATE message, and in some cases, of a WM_DDE_REQUEST message.

Parameters

When responding to WM_DDE_INITIATE:

hwnd

Value of wParam. Identifies the server window posting the message.

aApp

Value of the low-order word of lParam. Contains an atom that identifies the replying application.

aTopic

Value of the high-order word of lParam. Contains an atom that identifies the topic for which a conversation is being established.

When responding to WM_DDE_EXECUTE:

hwnd

Value of wParam. Identifies the server window posting the message.

lPackedVal

Value of lParam. The component parameters that are packed into lPackedVal are extracted by calling the UnpackDDElParam function. The low-order word is wStatus. The high-order word is the same hCommands that was received in the WM_DDE_EXECUTE message.

Parameter	Description
wStatus	Specifies a DDEACK structure containing a series of flags that indicate the status of the response.
hCommands	Identifies a global memory object that contains the command string.
When replying to all other messages:

hwnd

Value of wParam. Identifies the client or server window posting the message.

lPackedVal

Value of lParam. The component parameters that are packed into lPackedVal are extracted by calling the UnpackDDElParam function. The low-order word is wStatus. The high-order word is aItem.

Parameter	Description
wStatus	Specifies a DDEACK structure containing a series of flags that indicate the status of the response.
aItem	Contains a global atom that identifies the name of the data item for which the response is sent.
Remarks

Posting

Except in response to the WM_DDE_INITIATE message, the application posts the WM_DDE_ACK message by calling the PostMessage function, not by calling the SendMessage function. When responding to WM_DDE_INITIATE, the application sends the WM_DDE_ACK message by calling SendMessage. In this case, neither the application-name atom nor the topic-name atom should be NULL (even if the WM_DDE_INITIATE message specified NULL atoms).

When acknowledging any message with an accompanying aItem atom, the application posting WM_DDE_ACK can either reuse the aItem atom that accompanied the original message, or it can delete it and create a new one.

When acknowledging WM_DDE_EXECUTE, the application that posts WM_DDE_ACK should reuse the global memory object identified in the original WM_DDE_EXECUTE message.

All posted WM_DDE_ACK messages must create or reuse the lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function.

If an application has initiated the termination of a conversation by posting WM_DDE_TERMINATE and is awaiting confirmation, the waiting application should not acknowledge (positively or negatively) any subsequent messages sent by the other application. The waiting application should delete any atoms or shared memory objects received in these intervening messages. Memory objects should not be freed if the fRelease flag is set to FALSE in WM_DDE_POKE, and WM_DDE_DATA messages.

Receiving

The application that receives a WM_DDE_ACK message should delete all atoms accompanying the message. If the application receives a WM_DDE_ACK in response to a message with an accompanying hData object, and the object was sent with the fRelease flags set to FALSE, the application is responsible for deleteing the hData object.

If the application receives a negative WM_DDE_ACK message posted in reply to a WM_DDE_ADVISE message, the application should delete the global memory object posted with the original WM_DDE_ADVISE message (in hOptions). If the application receives a negative WM_DDE_ACK message posted in reply to a WM_DDE_DATA, WM_DDE_POKE, or WM_DDE_EXECUTE message, the application should delete the global memory object posted with the original WM_DDE_DATA, WM_DDE_POKE, or WM_DDE_EXECUTE message (in hCommands).

The application that receives a posted WM_DDE_ACK message must free the lPackedVal parameter by using the FreeDDElParam function.

See Also

DDEACK, FreeDDElParam, PackDDElParam, PostMessage, ReuseDDElParam, 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

WM_DDE_ADVISE

wParam = (WPARAM) hwnd;        // handle of posting application

lParam = (LPARAM) lPackedVal;  // packed DDEADVISE and item atom

A DDE client application posts the WM_DDE_ADVISE message to a DDE server application to request the server to supply an update for a data item whenever the item changes.

Parameters

hwnd

Value of wParam. Identifies the client window posting the message.

lPackedVal

Value of lParam. The component parameters packed into lPackedVal are extracted by calling the UnpackDDElParam function. The low-order word is hOptions. The high-order word is aItem.

Parameter	Description
hOptions	Identifies a global memory object containing a DDEADVISE structure that specifies how the data is to be sent.
aItem	Contains an atom that identifies the requested data item.
Remarks

If a client application supports more than one clipboard format for a single topic and item, it can post multiple WM_DDE_ADVISE messages for the topic and item, specifying a different clipboard format with each message. Note that a server can support multiple formats only for hot data links, not warm data links.

Posting

The client application posts the WM_DDE_ADVISE message by calling the PostMessage function, not the SendMessage function.

The client application allocates hOptions by calling the GlobalAlloc function with the GMEM_DDESHARE option. It allocates aItem by calling the GlobalAddAtom function.

The client application must create or reuse the WM_DDE_ADVISE lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with hOptions supplied as the low-order word and aItem supplied as the high-order word.

If the receiving (server) application responds with a negative WM_DDE_ACK message, the posting (client) application must delete the hOptions object.

The fRelease flag is not used in WM_DDE_ADVISE messages, but their data-freeing behavior is similar to that of WM_DDE_DATA and WM_DDE_POKE messages where fRelease is TRUE.

Receiving

The server application posts the WM_DDE_ACK message to respond positively or negatively. When posting WM_DDE_ACK, the application can reuse the aItem atom or delete it and create a new one. If the WM_DDE_ACK message is positive, the application should delete the hOptions object; otherwise, the application should not delete the object.

The server must create or reuse the WM_DDE_ACK lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with wStatus supplied as the low-order word and aItem supplied as the high-order word.

See Also

DDEADVISE, FreeDDElParam, GlobalAddAtom, GlobalAlloc, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK, WM_DDE_DATA, WM_DDE_POKE, WM_DDE_REQUEST


WM_DDE_DATA

WM_DDE_DATA

wParam = (WPARAM) hwnd;         // handle of posting application

lParam = (LPARAM) lPackedVal;   // packed DDEDATA and item atom

A DDE server application posts a WM_DDE_DATA message to a DDE client application to pass a data item to the client or to notify the client of the availability of a data item.

Parameters

hwnd

Value of wParam. Identifies the server window posting the message.

lPackedVal

Value of lParam. The component parameters that are packed into lPackedVal are extracted by calling the UnpackDDElParam function. The low-order word is hData or NULL. The high-order word is aItem.

Parameter	Description
hData	Identifies a global memory object containing a DDEDATA structure with the data and additional information. The handle should be set to NULL if the server is notifying the client that the data-item value has changed during a warm data link. A warm link is established by the client sending a WM_DDE_ADVISE message with the fDeferUpd bit set.
aItem	Contains an atom that identifies the data item for which the data or notification is sent.
Remarks

Posting

The server application posts the WM_DDE_DATA message by calling the PostMessage function, not the SendMessage function.

The server application allocates hData by calling the GlobalAlloc function with the GMEM_DDESHARE option. It allocates aItem by calling the GlobalAddAtom function.

The server must create or reuse the WM_DDE_DATA lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with hData supplied as the low-order word and aItem supplied as the high-order word.

If the receiving (client) application responds with a negative WM_DDE_ACK message, the posting (server) application must delete the hData object; otherwise, the client must delete the hData object after extracting its contents by calling the UnpackDDElParam function.

If the server application sets the fRelease member of the DDEDATA structure to FALSE, the server is responsible for deleting hData upon receiving either a positive or negative acknowledgement.

The server application should not set both the fAckReq and fRelease members of the DDEDATA structure to FALSE. If both members are set to FALSE, it is impossible for the server to determine when to delete hData.

Receiving

If fAckReq is TRUE, the client application should post the WM_DDE_ACK message to respond positively or negatively. When posting WM_DDE_ACK, the client can either reuse the aItem atom, or it can delete it and create a new one.

The client must create or reuse the WM_DDE_ACK lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with wStatus supplied as the low-order word and aItem supplied as the high-order word.

If fAckReq is FALSE, the client application should delete the aItem atom.

If the posting (server) application specified hData as NULL, the receiving (client) application can request the server to send the data by posting a WM_DDE_REQUEST message.

After processing a WM_DDE_DATA message in which hData is not NULL, the client should free hData, unless one of the following conditions is true:

•	The fRelease member is FALSE.

•	The fRelease member is TRUE, but the client application responds with a negative WM_DDE_ACK message.

See Also

DDEDATA, FreeDDElParam, GlobalAddAtom, GlobalAlloc, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK, WM_DDE_ADVISE, WM_DDE_POKE, WM_DDE_REQUEST


WM_DDE_EXECUTE

WM_DDE_EXECUTE

wParam = (WPARAM) hwnd;        // handle of posting application

lParam = (LPARAM) hCommands;   // handle to global object

A DDE client application posts a WM_DDE_EXECUTE message to a DDE server application to send a string to the server to be processed as a series of commands. The server application is expected to post a WM_DDE_ACK message in response.

Parameters

hwnd

Value of wParam. Identifies the client window posting the message.

hCommands

Value of lParam. Contains a global memory object that references an ANSI or Unicode command string, depending on the types of windows involved in the conversation.

Remarks

The command string is a null-terminated string consisting of one or more opcode strings enclosed in single brackets ([ ]).

Each opcode string has the following syntax, where the parameters list is optional:

opcode parameters

The opcode is any application-defined single token. It cannot include spaces, commas, parentheses, brackets, or quotation marks.

The parameters list can contain any application-defined value or values. Multiple parameters are separated by commas, and the entire parameter list is enclosed in parentheses. Parameters cannot include commas or parentheses except inside a quoted string. If a bracket or parenthesis character is to appear in a quoted string, it need not be doubled, as was the case under the old rules.

Following are some valid command strings:

[connect][download(query1,results.txt)][disconnect]

[query("sales per employee for each district")]

[open("sample.xlm")][run("r1c1")]

[quote_case("This is a "" character")]

[bracket_or_paren_case("()s or []s should be no problem.")]

Note that, under the old rules, parentheses and brackets had to be doubled, as follows:

[bracket_or_paren_case("(())s or [[]]s should be no problem.")]

Servers should be able to parse commands in either form.

Unicode execute strings should be used only when both the client and server window handles cause the IsWindowUnicode function to return TRUE.

Posting

The client application posts the WM_DDE_EXECUTE message by calling the PostMessage function, not the SendMessage function.

The client application allocates hCommands by calling the GlobalAlloc function with the GMEM_DDESHARE option.

When processing the WM_DDE_ACK message that the server posts in reply to a WM_DDE_EXECUTE message, the client application must delete the hCommands object sent back in the WM_DDE_ACK message.

Receiving

The server application posts the WM_DDE_ACK message to respond positively or negatively. The server should reuse the hCommands object.

Unless specified otherwise by a sub-protocol, the server should not post the WM_DDE_ACK message until all the actions specified by the execute command string are completed. The one exception to this rule is when the string causes the server to terminate the conversation.

See Also

GlobalAlloc, IsWindowUnicode, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK


WM_DDE_INITIATE

WM_DDE_INITIATE

wParam = (WPARAM) hwnd;             // handle of posting appl.

lParam = MAKELPARAM(aApp, aTopic);  // appl. and topic atoms

A DDE client application sends a WM_DDE_INITIATE message to initiate a conversation with a server application responding to the specified application and topic names. Upon receiving this message, all server applications with names that match the specified application and that support the specified topic are expected to acknowledge it. (For more information, see the WM_DDE_ACK message.)

Parameters

hwnd

Value of wParam. Identifies the client window sending the message.

aApp

Value of the low-order word of lParam. Contains an atom that identifies the application with which a conversation is requested. The application name cannot contain slashes (/) or backslashes (\). These characters are reserved for network implementations. If aApp is NULL, a conversation with all applications is requested.

aTopic

Value of the high-order word of lParam. Contains an atom that identifies the topic for which a conversation is requested. If the topic is NULL, conversations for all available topics are requested.

Remarks

If aApp is NULL, any server application can respond. If aTopic is NULL, any topic is valid. Upon receiving a WM_DDE_INITIATE request with the aTopic parameter set to NULL, a server must send a WM_DDE_ACK message for each of the topics it supports.

Sending

The client application sends WM_DDE_INITIATE by calling the SendMessage function, not the PostMessage function. The client broadcasts the message to all top-level windows by setting the first parameter of SendMessage to −1.

If the client application has already obtained the window handle of the desired server, it can send WM_DDE_INITIATE directly to the server window by passing the server's window handle as the first parameter of SendMessage.

The client application allocates aApp and aTopic by calling GlobalAddAtom.

When SendMessage returns, the client application must delete the aApp and aTopic atoms.

Receiving

To complete the initiation of a conversation, the server application must respond with one or more WM_DDE_ACK messages, where each message is for a separate topic. When sending WM_DDE_ACK message, the server should create new aApp and aTopic atoms; it should not reuse the atoms sent with WM_DDE_INITIATE.

See Also

GlobalAddAtom, GlobalAlloc, PostMessage, SendMessage, WM_DDE_ACK


WM_DDE_POKE

WM_DDE_POKE

wParam = (WPARAM) hwnd;        // handle of posting application

lParam = (LPARAM) lPackedVal;  // packed DDEPOKE and item atom

A DDE client application posts a WM_DDE_POKE message to a DDE server application. A client uses this message to request the server to accept an unsolicited data item. The server is expected to reply with a WM_DDE_ACK message indicating whether it accepted the data item.

Parameters

hwnd

Value of wParam. Identifies the client window posting the message.

lPackedVal

Value of lParam. The component parameters that are packed into lPackedVal are extracted by calling the UnpackDDElParam function. The low-order word is hData. The high-order word is aItem.

Parameter	Description
hData	Identifies a global memory object containing a DDEPOKE structure with the data and additional information.
aItem	Contains a global atom that identifies the data item for which the data or notification is being sent.
Remarks

Posting

The client application posts the WM_DDE_POKE message by using the PostMessage function.

The client application must allocate memory for the hData object by using the GlobalAlloc function with the GMEM_DDESHARE option. The client application must delete the hData object if either of the following conditions is true:

•	The server application responds with a negative WM_DDE_ACK message.

•	The fRelease member is FALSE, but the server application responds with either a positive or negative WM_DDE_ACK.

The client application must create the aItem atom by using the GlobalAddAtom function.

The client application must create or reuse the WM_DDE_POKE lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with hData supplied as the low-order word and aItem supplied as the high-order word.

Receiving

The server application should post the WM_DDE_ACK message to respond positively or negatively. When posting WM_DDE_ACK, the server can either reuse the aItem atom, or it can delete it and create a new one.

The server must create or reuse the WM_DDE_ACK lPackedVal parameter by calling the PackDDElParam function or the ReuseDDElParam function with wStatus supplied as the low-order word and aItem supplied as the high-order word.

To free the hData object, the server should call the GlobalFree function. Also, if the data format is either CF_DSPMETAFILEPICT or CF_METAFILEPICT, the server must also call DeleteMetaFile with the embedded metafile handle. These two formats have an extra level of indirection; that is, an application must lock hData to get a pointer to a handle, then lock that handle to get a pointer to a METAFILEPICT, and finally call DeleteMetaFile with the handle from the hMF member of the METAFILEPICT structure.

To free the lPackedVal object, the server should call the FreeDDElParam function.

See Also

DDEPOKE, DeleteMetaFile, FreeDDElParam, GlobalAddAtom, GlobalAlloc, GlobalFree, METAFILEPICT,, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK


WM_DDE_REQUEST

WM_DDE_REQUEST

wParam = (WPARAM) hwnd;        // handle of posting application

lParam = (LPARAM) lParam;      // holds cfFormat and aItem

A DDE client application posts a WM_DDE_REQUEST message to a DDE server application to request the value of a data item.

Parameters

hwnd

Value of wParam. Identifies the client window sending the message.

lParam

Holds the cfFormat and aItem parameters.

Parameter	Description
cfFormat	This is the LOWORD of lParam. Specifies a standard or registered clipboard format.
aItem	This is the HIWORD of lParam. Contains an atom that identifies the data item requested from the server.
Remarks

Posting

The client application posts the WM_DDE_REQUEST message by calling the PostMessage function, not the SendMessage function.

The client application allocates aItem by calling the GlobalAddAtom function.

Receiving

If the receiving (server) application can satisfy the request, it responds with a WM_DDE_DATA message containing the requested data. Otherwise, it responds with a negative WM_DDE_ACK message.

When responding with either a WM_DDE_DATA or WM_DDE_ACK message, the server application can either reuse the aItem atom or it can delete the atom and create a new one.

See Also

GlobalAddAtom, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK, WM_DDE_DATA


WM_DDE_TERMINATE

WM_DDE_TERMINATE

wParam = (WPARAM) hwnd; // handle of posting window

lParam = 0;             // not used, must be zero

A DDE application (client or server) posts a WM_DDE_TERMINATE message to terminate a conversation.

Parameters

hwnd

Value of wParam. Identifies the client or server window posting the message.

Remarks

Posting

The client or server application posts the WM_DDE_TERMINATE message by calling the PostMessage function, not the SendMessage function.

While waiting for confirmation of the termination, the posting application should not post any other messages to the receiving application. If the sending application receives messages (other than WM_DDE_TERMINATE) from the receiving application, it should delete any atoms or shared memory objects accompanying the messages, except hData objects associated with WM_DDE_POKE or WM_DDE_DATA messages that do not have the fRelease flag set.

Receiving

The client or server application should respond by posting a WM_DDE_TERMINATE message.

See Also

PostMessage, SendMessage, WM_DDE_DATA, WM_DDE_POKE


WM_DDE_UNADVISE

WM_DDE_UNADVISE

wParam = (WPARAM) hwnd;        // handle of posting application

lParam = (LPARAM) lParam;      // format and item atom

A DDE client application posts a WM_DDE_UNADVISE message to inform a DDE server application that the specified item or a particular clipboard format for the item should no longer be updated. This terminates the warm or hot data link for the specified item.

Parameters

hwnd

Value of wParam. Identifies the client window sending the message.

lParam

Holds the cfFormat and aItem parameters.

Parameter	Description
cfFormat	This is the LOWORD of lParam. Specifies the clipboard format of the item for which the update request is being retracted. If cfFormat is NULL, all active WM_DDE_ADVISE conversations for the item are to be terminated.
aItem	This is the HIWORD of lParam. Contains a global atom that identifies the item for which the update request is being retracted. When aItem is NULL, all active WM_DDE_ADVISE links associated with the conversation are to be terminated.
Remarks

Posting

The client application posts the WM_DDE_UNADVISE message by calling the PostMessage function, not the SendMessage function.

The client application allocates aItem by calling the GlobalAddAtom function.

Receiving

The server application posts the WM_DDE_ACK message to respond positively or negatively. When posting WM_DDE_ACK, the server can either reuse the aItem atom, or it can delete the atom and create a new one.

See Also

GlobalAddAtom, PackDDElParam, PostMessage, ReuseDDElParam, SendMessage, UnpackDDElParam, WM_DDE_ACK, WM_DDE_ADVISE


WM_DEADCHAR

WM_DEADCHAR

chCharCode = (TCHAR) wParam;    // character code

lKeyData = lParam;              // key data

The WM_DEADCHAR message is posted to the window with the keyboard focus when a WM_KEYUP message is translated by the TranslateMessage function. WM_DEADCHAR specifies a character code generated by a dead key. A dead key is a key that generates a character, such as the umlaut (double-dot), that is combined with another character to form a composite character. For example, the umlaut-O character (Ö) is generated by typing the dead key for the umlaut character, and then typing the O key.

Parameters

chCharCode

Value of wParam. Specifies the character code generated by the dead key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.
Return Value

An application should return zero if it processes this message.

Remarks

The WM_DEADCHAR message typically is used by applications to give the user feedback about each key pressed. For example, an application can display the accent in the current character position without moving the caret.

Because there is not necessarily a one-to-one correspondence between keys pressed and character messages generated, the information in the high-order word of the lKeyData parameter is generally not useful to applications. The information in the high-order word applies only to the most recent WM_KEYDOWN message that precedes the posting of the WM_DEADCHAR message.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateMessage, WM_KEYDOWN, WM_KEYUP, WM_SYSDEADCHAR


WM_DELETEITEM

WM_DELETEITEM

idCtl = wParam;                      // control identifier

lpdis = (LPDELETEITEMSTRUCT) lParam; // structure with item information

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.

Parameters

idCtl

Value of wParam. Specifies the identifier of the control that sent the WM_DELETEITEM message.

lpdis

Value of lParam. Points to a DELETEITEMSTRUCT structure that contains information about the item deleted from a list box.

Return Value

An application should return TRUE if it processes this message.

See Also

CB_DELETESTRING, CB_RESETCONTENT, DELETEITEMSTRUCT, LB_DELETESTRING, LB_RESETCONTENT


WM_DESTROY

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.

Return Value

If an application processes this message, it should return zero.

Remarks

If the window being destroyed is part of the clipboard viewer chain (set by calling the SetClipboardViewer function), the window must remove itself from the chain by processing the ChangeClipboardChain function before returning from the WM_DESTROY message.

See Also

ChangeClipboardChain, DestroyWindow, PostQuitMessage, SetClipboardViewer, WM_CLOSE


WM_DESTROYCLIPBOARD

WM_DESTROYCLIPBOARD

The WM_DESTROYCLIPBOARD message is sent to the clipboard owner when a call to the EmptyClipboard function empties the clipboard.

Parameters

This message has no parameters.

Return Value

If an application processes this message, it should return zero.

See Also

EmptyClipboard


WM_DEVICECHANGE  (preliminaryWindows 95)
WM_DEVICECHANGE  (preliminary−Windows 95)

Event = (UINT) wParam;
dwData = (DWORD) lParam;

The WM_DEVICECHANGE device message notifies an application or device driver of a change to the hardware configuration of a device or the computer.

Parameters

Event

Event type. Can be one of these values:

Value	Meaning
DBT_DEVICEARRIVAL	A device has been inserted and is now available.
DBT_DEVICEQUERYREMOVE	Permission to remove a device is requested. Any application can deny this request and cancel the removal.
DBT_DEVICEQUERYREMOVEFAILED	Request to remove a device has been canceled.
DBT_DEVICEREMOVEPENDING	Device is about to be removed. Can not be denied.
DBT_DEVICEREMOVECOMPLETE	Device has been removed.
DBT_DEVICETYPESPECIFIC	Device-specific event.
DBT_CONFIGCHANGED	Current configuration has changed.
DBT_DEVNODES_CHANGED	Device node has changed.
dwData

Address of a structure that contains event-specific data. Its meaning depends on the given event.

Return Value

Returns TRUE to complete a requested action, FALSE otherwise.

Remarks

For devices that offer software-controllable features, such as ejection and locking, the operating system typically sends a DBT_DEVICEREMOVEPENDING message to let applications and device drivers end their use of the device gracefully.

If the operating system forcefully removes of a device, it may not send a DBT_DEVICEQUERYREMOVE message before doing so.

DBT_CONFIGCHANGED, DBT_DEVICEARRIVAL, DBT_DEVICEQUERYREMOVE, DBT_DEVICEQUERYREMOVEFAILED, DBT_DEVICEREMOVECOMPLETE, DBT_DEVICEREMOVEPENDING, DBT_DEVICETYPESPECIFIC


WM_DEVMODECHANGE

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.

Parameters

lpszDev

Value of lParam. Points to the device name specified in the WIN.INI file.

Return Value

An application should return zero if it processes this message.

Remarks

Windows NT only: Calls to functions that change the WIN.INI file may be mapped to the registry instead. This mapping occurs when WIN.INI and the section being changed are specified in the registry under the following keys:

HKEY_LOCAL_MACHINE\Software\Description\Microsoft\
        Windows NT\CurrentVersion\IniFileMapping

The change in the storage location has no effect on the behavior of this message.

See Also

WM_WININICHANGE


WM_DISPLAYCHANGE  (preliminaryWindows 95)
WM_DISPLAYCHANGE  [image]  (preliminary−Windows 95)

WM_DISPLAYCHANGE

cBitsPerPixel = wParam;

cxScreen = LOWORD(lParam);

cyScreen = HIWORD(lParam);

The WM_DISPLAYCHANGE message is sent to all windows when the display resolution has changed.

Parameters

cBitsPerPixel

Specifies the new image depth of the display in bits per pixel.

cxScreen

Specifies the new horizontal resolution of the screen.

cyScreen

Specifies the new vertical resolution of the screen.

Remarks

In previous versions, this message was sent twice, once in anticipation of a change to the display resolution and once after the display resolution changed. Now it is only sent after the display resolution has changed.


WM_DRAWCLIPBOARD

WM_DRAWCLIPBOARD

The WM_DRAWCLIPBOARD message is sent to the first window in the clipboard viewer chain when the content of the clipboard changes. This enables a clipboard viewer window to display the new content of the clipboard.

Parameters

This message has no parameters.

Remarks

Only clipboard viewer windows receive this message. These are windows that have been added to the clipboard viewer chain by using the SetClipboardViewer function.

Each window that receives the WM_DRAWCLIPBOARD message must call the SendMessage function to pass the message on to the next window in the clipboard viewer chain. The handle of the next window in the chain is returned by SetClipboardViewer, and may change in response to a WM_CHANGECBCHAIN message.

See Also

SendMessage, SetClipboardViewer, WM_CHANGECBCHAIN


WM_DRAWITEM

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.

Parameters

idCtl

Value of wParam. Specifies the identifier of the control that sent the WM_DRAWITEM message. If the message was sent by a menu, this parameter is zero.

lpdis

Value of lParam. Points to a DRAWITEMSTRUCT structure containing information about the item to be drawn and the type of drawing required.

Return Value

If an application processes this message, it should return TRUE.

Default Action

The DefWindowProc function draws the focus rectangle for an owner-drawn list box item.

Remarks

The itemAction member of the DRAWITEMSTRUCT structure specifies the drawing operation that an application should perform.

Before returning from processing this message, an application should ensure that the device context identified by the hDC member of the DRAWITEMSTRUCT structure is in the default state.

See Also

DefWindowProc, DRAWITEMSTRUCT


WM_DROPFILES

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.

Parameters

hDrop

Value of wParam. Identifies an internal structure describing the dropped files. This handle is used by the DragFinish, DragQueryFile, and DragQueryPoint functions to retrieve information about the dropped files.

Return Value

An application should return zero if it processes this message.

See Also

DragAcceptFiles, DragFinish, DragQueryFile, DragQueryPoint


WM_ENABLE

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_DISABLED style bit) of the window has changed.

Parameters

fEnabled

Value of wParam. Specifies whether the window has been enabled or disabled. This parameter is TRUE if the window has been enabled or FALSE if the window has been disabled.

Return Value

If an application processes this message, it should return zero.

See Also

EnableWindow


WM_ENDSESSION

Windows 95:

WM_ENDSESSION

fEndSession = (BOOL) wParam;    // end-session flag

fLogOff = (BOOL) lParam         // logoff flag

Windows NT:

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.

Parameters

fEndSession

Value of wParam. Specifies whether the session is being ended. If the session is being ended, this parameter is TRUE; otherwise, it is FALSE.

fLogOff

Windows 95 only: Value of lParam. Indicates whether the user is logging off or shutting down the system. This parameter is TRUE if the user is logging off; it is FALSE if the user is shutting down the system.

Return Value

If an application processes this message, it should return zero.

Remarks

If the fEndSession parameter is TRUE, the Windows session can end any time after all applications have returned from processing this message. Therefore, an application should perform all tasks required for termination before returning from this message.

Note that lParam is not used on the Windows NT platform but is used on the Windows 95 platform.

The application need not call the DestroyWindow or PostQuitMessage function when the session is ending.

See Also

DestroyWindow, PostQuitMessage, WM_QUERYENDSESSION


WM_ENTERIDLE

WM_ENTERIDLE

fuSource = wParam;    // idle-source flag

hwnd = (HWND) lParam; // handle of dialog box or owner window

The WM_ENTERIDLE message is sent to the owner window of a modal dialog box or menu that is entering an idle state. A modal dialog box or menu enters an idle state when no messages are waiting in its queue after it has processed one or more previous messages.

Parameters

fuSource

Value of wParam. Specifies whether the message is the result of a dialog box or a menu being displayed. This parameter can be one of the following values:

Value	Meaning
MSGF_DIALOGBOX	The system is idle because a dialog box is displayed.
MSGF_MENU	The system is idle because a menu is displayed.
hwnd

Value of lParam. Contains the handle of the dialog box (if fuSource is MSGF_DIALOGBOX) or of the window containing the displayed menu (if fuSource is MSGF_MENU).

Return Value

An application should return zero if it processes this message.

Remarks

The DefWindowProc function returns zero.

See Also

DefWindowProc


WM_ENTERMENULOOP

WM_ENTERMENULOOP

wParam = (BOOL) fIsTrackPopupMenu  // flags a pop-up 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.

Parameters

fIsTrackPopupMenu

Specifies whether the menu involved is a pop-up menu. This parameter has a value of TRUE if it is a pop-up, FALSE if it isn't.

Return Value

An application should return zero if it processes this message.

Remarks

The DefWindowProc function returns zero.

See Also

WM_EXITMENULOOP


WM_ENTERSIZEMOVE  (preliminaryWindows NT)
WM_ENTERSIZEMOVE  (preliminary−Windows NT)

WM_ENTERSIZEMOVE

wParam = 0;  // not used, must be zero

lParam = 0;  // not used, must be zero

The WM_ENTERSIZEMOVE message is sent once to a window when it enters the moving or sizing mode. The window enters the moving or sizing mode when the user clicks the window's title bar or sizing border, or when the window passes the WM_SYSCOMMAND message to the DefWindowProc function and the wParam parameter of the message specifies the SC_MOVE or SC_SIZE value. Windows sends the WM_ENTERSIZEMOVE message regardless of whether the dragging of full windows is enabled.

Parameters

This message has no parameters.

Return Value

An application should return zero if it processes this message.

See Also

DefWindowProc, WM_EXITSIZEMOVE, WM_SYSCOMMAND


WM_ERASEBKGND

WM_ERASEBKGND

hdc = (HDC) wParam; // handle of device context

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.

Parameters

hdc

Value of wParam. Identifies the device context.

Return Value

An application should return nonzero if it erases the background; otherwise, it should return zero.

Remarks

The DefWindowProc function erases the background by using the class background brush specified by the hbrBackground member of the WNDCLASS structure. If hbrBackground is NULL, the application should process the WM_ERASEBKGND message and erase the background.

An application should return nonzero in response to WM_ERASEBKGND if it processes the message and erases the background; this indicates that no further erasing is required. If the application returns zero, the window will remain marked for erasing. (Typically, this indicates that the fErase member of the PAINTSTRUCT structure will be TRUE.)

See Also

BeginPaint, PAINTSTRUCT, WM_ICONERASEBKGND, WNDCLASS


WM_EXITMENULOOP

WM_EXITLOOP

wParam = (BOOL) fIsTrackPopupMenu    // flags a pop-up 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.

Parameters

fIsTrackPopupMenu

Specifies whether the menu involved is a pop-up menu. This parameter has a value of TRUE if it is a pop-up, FALSE if it isn't.

Return Value

An application should return zero if it processes this message.

Remarks

The DefWindowProc function returns zero.

See Also

WM_ENTERMENULOOP


WM_EXITSIZEMOVE  (preliminaryWindows NT)
WM_EXITSIZEMOVE  (preliminary−Windows NT)

WM_EXITSIZEMOVE

wParam = 0;  // not used; must be zero

lParam = 0;  // not used; must be zero

The WM_EXITSIZEMOVE message is sent once to a window after it has exited the moving or sizing mode.

Parameters

This message has no parameters.

Return Value

An application should return zero if it processes this message.

See Also

WM_ENTERSIZEMOVE


WM_FONTCHANGE

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.

Remarks

An application that adds or removes fonts from the system (for example, by using the AddFontResource or RemoveFontResource function) should send this message to all top-level windows.

To send the WM_FONTCHANGE message to all top-level windows, an application can call the SendMessage function with the hwnd parameter set to HWND_BROADCAST.

See Also

AddFontResource, RemoveFontResource, SendMessage


WM_GETDLGCODE

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.

Return Value

The return value is one or more of the following values, indicating which type of input the application processes.

Value	Meaning
DLGC_BUTTON	Button.
DLGC_DEFPUSHBUTTON	Default push button.
DLGC_HASSETSEL	EM_SETSEL messages.
DLGC_RADIOBUTTON	Radio button.
DLGC_STATIC	Static control.
DLGC_UNDEFPUSHBUTTON	Nondefault push button.
DLGC_WANTALLKEYS	All keyboard input.
DLGC_WANTARROWS	Direction keys.
DLGC_WANTCHARS	WM_CHAR messages.
DLGC_WANTMESSAGE	All keyboard input (the application passes this message on to a control).
DLGC_WANTTAB	TAB key.
Default Action

The DefWindowProc function returns zero.

Remarks

Although the DefWindowProc function always returns zero in response to the WM_GETDLGCODE message, the window procedure for the predefined control classes return a code appropriate for each class.

The WM_GETDLGCODE message and the returned values are useful only with user-defined dialog box controls or standard controls modified by subclassing.

See Also

DefWindowProc, EM_SETSEL, WM_CHAR


WM_GETFONT

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.

Return Value

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

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.

Return Value

The return value is the virtual-key code and modifiers for the hot key, or NULL if no hot key is associated with the window. The virtual-key code is in the low byte of the return value and the modifiers are in the high byte. The modifiers can be a combination of the following flags:

Value	Meaning
HOTKEYF_ALT	ALT key
HOTKEYF_CONTROL	CTRL key
HOTKEYF_EXT	Extended key
HOTKEYF_SHIFT	SHIFT key
Remarks

These hot keys are unrelated to the hot keys set by the RegisterHotKey function.

See Also

RegisterHotKey, WM_SETHOTKEY


WM_GETICON  (preliminaryWindows 95)
WM_GETICON  [image]  (preliminary−Windows 95)

WM_GETICON

fType = (BOOL) wParam;  // icon-size flag

The WM_GETICON message is sent to a window to retrieve the handle of the big or small icon associated with a window. Windows retrieves the big icon when drawing a minimized window, and retrieves the small icon when drawing a title bar.

Parameters

fType

Value of wParam. Specifies the icon to retrieve. If TRUE, the message retrieves the big icon; if FALSE, it retrieves the small icon.

Return Value

The return value is the handle of the big or small icon, depending on the value of fType. When an application receives this message, it can return the handle of a big or small icon, or pass the message to DefWindowProc.

Default Action

DefWindowProc returns the handle of the big or small icon associated with the window, depending on the value of fType.

Remarks

When an application receives this message, it can return the handle of a big or small icon, or pass the message to DefWindowProc.

See Also

DefWindowProc, WM_SETICON


WM_GETMINMAXINFO

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.

Parameters

lpmmi

Value of lParam. Points to a MINMAXINFO structure that contains the default maximized position and dimensions, and the default minimum and maximum tracking sizes. An application can override the defaults by setting the members of this structure.

Return Value

If an application processes this message, it should return zero.

Remarks

The maximum tracking size is the largest window size that can be produced by using the borders to size the window. The minimum tracking size is the smallest window size that can be produced by using the borders to size the window.

See Also

MoveWindow, SetWindowPos, MINMAXINFO


WM_GETTEXT

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.

Parameters

cchTextMax

Value of wParam. Specifies the maximum number of characters to be copied, including the terminating null character.

lpszText

Value of lParam. Points to the buffer that is to receive the text.

Return Value

The return value is the number of characters copied.

Default Action

The DefWindowProc function copies the text associated with the window into the specified buffer and returns the number of characters copied.

Remarks

For an edit control, the text to be copied is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To copy the text of an item in a list box, an application can use the LB_GETTEXT message.

When the WM_GETTEXT message is sent to a static control with the SS_ICON style, the handle of the icon will be returned in the first four bytes of the buffer pointed to by lpszText. This is true only if the WM_SETTEXT message has been used to set the icon.

See Also

DefWindowProc, GetWindowText, GetWindowTextLength, LB_GETTEXT, WM_GETTEXTLENGTH, WM_SETTEXT


WM_GETTEXTLENGTH

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.

Return Value

The return value is the length, in characters, of the text.

Default Action

The DefWindowProc function returns the length, in characters, of the text. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section.

Remarks

For an edit control, the text to be copied is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To determine the length of an item in a list box, an application can use the LB_GETTEXTLEN message.

Under certain conditions, the DefWindowProc function returns a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the operating system allowing for the possible existence of DBCS characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

See Also

CB_GETLBTEXT, DefWindowProc, GetWindowText, GetWindowTextLength, LB_GETTEXT, LB_GETTEXTLEN, WM_GETTEXT


WM_HELP  (preliminaryWindows NT)
WM_HELP  [image]  (preliminary−Windows NT)

WM_HELP

lphi = (LPHELPINFO) lParam;

The WM_HELP message indicates that the user pressed the F1 key. If a menu is active when F1 is pressed, WM_HELP is sent to the window associated with the menu; otherwise, WM_HELP is sent to the window that has the keyboard focus. If no Window has the keyboard focus, WM_HELP is sent to the currently active window.

Parameters

lphi

Pointer to a HELPINFO structure that contains information about the menu item, control, dialog box, or window for which help is requested.

Return Value

Returns TRUE.

Remarks

The DefWindowProc function passes WM_HELP to the parent window of a child window or to the owner of a top-level window.

See Also

DefWindowProc, HELPINFO


WM_HOTKEY

WM_HOTKEY

idHotKey = (int) wParam;              // identifier of hot key

fuModifiers = (UINT) LOWORD(lParam);  // key-modifier flags

uVirtKey = (UINT) HIWORD(lParam);     // virtual-key code

The WM_HOTKEY message is posted when the user presses a hot key registered by the RegisterHotKey function. The message is placed at the top of the message queue associated with the thread that registered the hot key.

Parameters

idHotKey

Value of wParam. Specifies the identifier of the hot key that generated the message. If the message was generated by a system-defined hot key, the idHotKey parameter will be one of the following values:

Value	Meaning
IDHOT_SNAPDESKTOP	The "snap desktop" hot key was pressed.
IDHOT_SNAPWINDOW	The "snap window" hot key was pressed.
fuModifiers

Specifies the keys that were to be pressed in combination with the key specified by the nVirtKey parameter to generate the WM_HOTKEY message. The fuModifiers parameter can be a combination of the following values:

Value	Meaning
MOD_ALT	Either ALT key was held down.
MOD_CONTROL	Either CTRL key was held down.
MOD_SHIFT	Either SHIFT key was held down.
MOD_WIN	Either WINDOWS key was held down. These keys appear only on the Microsoft Ergonomic Keyboard and are labeled with the Microsoft Windows logo.
uVirtKey

Specifies the virtual key code of the hot key.

Remarks

WM_HOTKEY is unrelated to the WM_GETHOTKEY and WM_SETHOTKEY hot keys. The WM_HOTKEY message is sent for generic hot keys while the WM_SET\GETHOTKEY messages relate to window activation hot keys.

See Also

RegisterHotKey, WM_GETHOTKEY, WM_SETHOTKEY


WM_HSCROLL

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.

Parameters

nScrollCode

Value of the low-order word of wParam. Specifies a scroll bar value that indicates the user's scrolling request. This parameter can be one of the following values:

Value	Meaning
SB_BOTTOM	Scrolls to the lower right.
SB_ENDSCROLL	Ends scroll.
SB_LINELEFT	Scrolls left by one unit.
SB_LINERIGHT	Scrolls right by one unit.
SB_PAGELEFT	Scrolls left by the width of the window.
SB_PAGERIGHT	Scrolls right by the width of the window.
SB_THUMBPOSITION	Scrolls to the absolute position. The current position is specified by the nPos parameter.
SB_THUMBTRACK	Drags scroll box to the specified position. The current position is specified by the nPos parameter.
SB_TOP	Scrolls to the upper left.
nPos

Value of the high-order word of wParam. Specifies the current position of the scroll box if the nScrollCode parameter is SB_THUMBPOSITION or SB_THUMBTRACK; otherwise, nPos is not used.

hwndScrollBar

Value of lParam. Identifies the control if WM_HSCROLL is sent by a scroll bar control. If WM_HSCROLL is sent by a window's standard scroll bar, hwndScrollBar is not used.

Return Value

If an application processes this message, it should return zero.

Remarks

The SB_THUMBTRACK notification message is typically used by applications that provide feedback as the user drags the scroll box.

If an application scrolls the content of the window, it must also reset the position of the scroll box by using the SetScrollPos function.

Note that the WM_HSCROLL message carries only 16 bits of scroll box position data. Thus, applications that rely solely on WM_HSCROLL (and WM_VSCROLL) for scroll position data have a practical maximum position value of 65,535.

However, because the SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, GetScrollRange, SetScrollPos, SetScrollRange, WM_VSCROLL


WM_HSCROLLCLIPBOARD

WM_HSCROLLCLIPBOARD

hwndViewer = (HWND) wParam;         // handle of clipboard viewer window

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. This occurs when the clipboard contains data in the CF_OWNERDISPLAY format and an event occurs in the clipboard viewer's horizontal scroll bar. The owner should scroll the clipboard image and update the scroll bar values.

Parameters

hwndViewer

Value of wParam. Identifies the clipboard viewer window.

nScrollCode

Value of the low-order word of lParam. Specifies a scroll bar event. This parameter can be one of the following values:

Value	Meaning
SB_BOTTOM	Scroll to lower right.
SB_ENDSCROLL	End scroll.
SB_LINEDOWN	Scroll one line down.
SB_LINEUP	Scroll one line up.
SB_PAGEDOWN	Scroll one page down.
SB_PAGEUP	Scroll one page up.
SB_THUMBPOSITION	Scroll to absolute position. The current position is specified by the nPos parameter.
SB_TOP	Scroll to upper left.
nPos

Value of the high-order word of lParam. Specifies the current position of the scroll box if the nScrollCode parameter is SB_THUMBPOSITION; otherwise, the nPos parameter is not used.

Return Value

If an application processes this message, it should return zero.

Remarks

The clipboard owner can use the ScrollWindow function to scroll the image in the clipboard viewer window and invalidate the appropriate region.

See Also

ScrollWindow


WM_ICONERASEBKGND

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.

Parameters

hdc

Value of wParam. Identifies the device context of the icon.

Return Value

An application should return nonzero if it processes this message.

Remarks

The DefWindowProc function fills the icon background with the class background brush of the parent window.

See Also

DefWindowProc, WM_ERASEBKGND


WM_IME_CHAR  (preliminaryWindows 95)
WM_IME_CHAR  (preliminary−Windows 95)

chCharCode1 = (TCHAR) wParam;
chCharCode2 = (TCHAR) wParam>>8;
lKeyData = lParam;

The WM_IME_CHAR message is sent to an application when the IME gets a character of the conversion result. Unlike the WM_CHAR message, this message can include double-byte as well as single-byte character values.

Parameters

chCharCode1 and chCharCode2

Single- or double-byte character value.

lKeyData

Repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown following:

Bit	Meaning
0 - 15	Repeat count: Since the first byte and second byte is continuous, this is always 1.
16 - 23	Scan Code: Scan code for complete a FE character.
24 - 28	Not used.
29	Context code.
31	Conversion state.
Remarks

If the WM_IME_CHAR message includes a double-byte character, the DefWindowProc function converts this message into two WM_CHAR messages, each containing one byte of the double-byte character.

See Also

DefWindowProc, WM_CHAR


WM_IME_COMPOSITION  (preliminaryWindows 95)
WM_IME_COMPOSITION  (preliminary−Windows 95)

chDBCS = (WORD) wParam;
fFlags = (BOOL) lParam;

The WM_IME_COMPOSITION message is sent to an application when the IME changes composition status as a result of a key stroke. An application should process this message if it displays composition characters itself. Otherwise, it should send the message to the IME window.

Parameters

chDBCS

DBCS character representing the latest change to the composition string.

fFlags

Change flag, indicating how the composition string or character changed. This parameter can be one or more of the following values:

GCS_COMPSTR	GCS_SETCURSORPOS
GCS_COMPATTR	GCS_RESULTSTR
GCS_COMPCLAUSE	GCS_RESULTCLAUSE
GCS_COMPREADSTR	GCS_RESULTREADSTR
GCS_COMPREADATTR	GCS_RESULTREADCLAUSE
GCS_COMPREADCLAUSE	GCR_ERRORSTR
GCS_TYPINGINFO	GCR_INFOSTR
Return Value

No return value.

Remarks

The fFlags parameter can also be a combination of the following values:

Value	Meaning
CS_INSERTCHAR	Specifies that the given composition character should be inserted at the current insertion point. An application should display the composition character if it processes this message.
CS_NOMOVECARET	Specifies that the application must not move the caret position as a result of processing the message. For example, if an IME specifies a combination of CS_INSERTCHAR and CS_NOMOVECARET, the application should insert the given character at the current caret position but should not move caret to the next position. A subsequent WM_IME_COMPOSITION message with GCS_RESULTSTR will replace this character.
If the application has created an IME window, it should pass this message to that window. The DefWindowProc function processes this message by passing it to the default IME window.The IME window processes this message by updating its appearance based on the change flag given. An application can call ImmGetCompositionString to retrieve the new composition status.

See Also

DefWindowProc, ImmGetCompositionString


WM_IME_COMPOSITIONFULL(preliminaryWindows 95)
WM_IME_COMPOSITIONFULL  (preliminary−Windows 95)

The WM_IME_COMPOSITIONFULL message is sent to an application when the IME window finds no space to extend the area for the composition window. The application should use the IMC_SETCOMPOSITIONWINDOW message to specify how to display the window.

Return Value

No return value.

Remarks

The wParam and lParam parameters are not used. The IME window, not the IME, sends this notification message by using the SendMessage message.

See Also

IMC_SETCOMPOSITIONWINDOW, SendMessage


WM_IME_CONTROL  (preliminaryWindows 95)
WM_IME_CONTROL  (preliminary−Windows 95)

wParam = (WPARAM) (DWORD) dwCommand;
lParam = (LPARAM) (DWORD) dwData;

The WM_IME_CONTROL message directs the IME window to carry out the requested command. An application uses this message to control the IME window created by the application.

Parameters

dwCommand

Command value. This parameter can be one of the following values:

IMC_GETCANDIDATEPOS	IMC_OPENSTATUSWINDOW
IMC_GETCOMPOSITIONFONT	IMC_SETCANDIDATEPOS
IMC_GETCOMPOSITIONWINDOW	IMC_SETCOMPOSITIONFONT
IMC_GETCONVERSIONMODE	IMC_SETCOMPOSITIONWINDOW
IMC_GETOPENSTATUS	IMC_SETCONVERSIONMODE
IMC_GETSENTENCEMODE	IMC_SETOPENSTATUS
IMC_GETSTATUSWINDOWPOS	IMC_SETSENTENCEMODE
IMC_CLOSESTATUSWINDOW	IMC_SETSTATUSWINDOWPOS
For more information about these commands, see the individual descriptions.

dwData

Command-specific value.

Return Value

Returns a command-specific value.

See Also

IMC_GETCANDIDATEPOS, IMC_GETCOMPOSITIONFONT, IMC_GETCOMPOSITIONWINDOW, IMC_GETCONVERSIONMODE, IMC_GETOPENSTATUS, IMC_GETSENTENCEMODE, IMC_GETSTATUSWINDOWPOS, IMC_SETCANDIDATEPOS, IMC_SETCOMPOSITIONFONT, IMC_SETCOMPOSITIONWINDOW, IMC_SETCONVERSIONMODE, IMC_SETOPENSTATUS, IMC_SETSENTENCEMODE, IMC_SETSTATUSWINDOWPOS


WM_IME_ENDCOMPOSITION(preliminaryWindows 95)
WM_IME_ENDCOMPOSITION  (preliminary−Windows 95)

The WM_IME_ENDCOMPOSITION message is sent to an application when the IME ends composition. An application should process this message if it displays composition characters itself.

Return Value

No return value.

Remarks

The wParam and lParam parameters are not used.

If an application has created an IME window, it should pass this message to that window. The DefWindowProc function processes this message by passing it to default IME window.

See Also

DefWindowProc


WM_IME_KEYDOWN

nVirtKey = (int) wParam;    // virtual-key code
lKeyData = lParam;          // key data

The WM_IME_KEYDOWN message is sent to an application by the IME to notify the application of a key press. The parameters and return value for this message are identical to the WM_KEYDOWN message. An application can process this message or pass it to the DefWindowProc function to generate a matching WM_KEYDOWN message. This message is usually generated by the IME to keep message order.

See Also

DefWindowProc


WM_IME_KEYUP

nVirtKey = (int) wParam;    // virtual-key code
lKeyData = lParam;          // key data

The WM_IME_KEYUP message is sent to an application by the IME to notify the application of a key release. The parameters and return value for this message are identical to the WM_KEYUP message. An application can process this message or pass it to the DefWindowProc function to generate a matching WM_KEYUP message. This message is usually generated by the IME to keep message order.

See Also

DefWindowProc


WM_IME_NOTIFY  (preliminaryWindows 95)
WM_IME_NOTIFY  (preliminary−Windows 95)

dwCommand = (DWORD) wParam;
dwData = (DWORD) lParam;

The WM_IME_NOTIFY message is sent to an application to notify it of changes to the IME window. An application processes this message if it is responsible for managing the IME window.

Parameters

dwCommand

Command value. This parameter may be one of the following values:

IMN_CHANGECANDIDATE	IMN_SETCANDIDATEPOS
IMN_CLOSECANDIDATE	IMN_SETCOMPOSITIONFONT
IMN_CLOSESTATUSWINDOW	IMN_SETCOMPOSITIONWINDOW
IMN_GUIDELINE	IMN_SETCONVERSIONMODE
IMN_OPENCANDIDATE	IMN_SETOPENSTATUS
IMN_OPENSTATUSWINDOW	IMN_SETSENTENCEMODE
IMN_PRIVATE	IMN_SETSTATUSWINDOWPOS
For more information about these commands, see the corresponding descriptions.

dwData

Command-specific value.

Return Value

Returns a command-specific value.

IMN_CHANGECANDIDATE, IMN_OPENCANDIDATE, IMN_OPENSTATUSWINDOW, IMN_PRIVATE, IMN_SETCANDIDATEPOS, IMN_SETCOMPOSITIONFONT, IMN_SETCOMPOSITIONWINDOW, IMN_SETCONVERSIONMODE, IMN_SETOPENSTATUS, IMN_SETSENTENCEMODE, IMN_SETSTATUSWINDOWPOS


WM_IME_SELECT  (preliminaryWindows 95)
WM_IME_SELECT  (preliminary−Windows 95)

fSeleft = (BOOL) wParam;
hKL = (HANDLE) lParam;

The WM_IME_SELECT message is sent to an application when the system is about to change the current IME. An application that has created an IME window should pass this message to that window so that it can retrieve the keyboard layout handle for the newly selected IME.

Parameters

fSelect

Selection flag. If TRUE, the specified IME is selected; if FALSE, the specified IME is no longer selected.

hKL

Handle to the keyboard layout associated with the IME.

Return Value

No return value.

Remarks

The DefWindowProc function processes this message by passing the information to the default IME window.

See Also

DefWindowProc


WM_IME_SETCONTEXT  (preliminaryWindows 95)
WM_IME_SETCONTEXT  (preliminary−Windows 95)

fSet = (BOOL) wParam;
hContext = (HANDLE) lParam;

The WM_IME_SETCONTEXT message is sent to an application when a window is activated. If the application has created an IME window, it should call the ImmIsUIMessage function; otherwise, it should pass this message to the DefWindowProc function.

Parameters

fSet

Active flag. If TRUE, the input context is active. Otherwise, the context is inactive.

hContext

Handle to the input context for the window.

Return Value

Return zero if the message processed.


WM_IME_STARTCOMPOSITION(preliminaryWindows 95)
WM_IME_STARTCOMPOSITION  (preliminary−Windows 95)

The WM_IME_STARTCOMPOSITION message is sent immediately before the IME generates composition string as a result of a key stroke. The message is a notification to an IME window to open its composition window. An application should process this message if it displays composition characters itself.

Return Value

No return value.

Remarks

The wParam and lParam parameters are not used.

If an application has created an IME window, it should pass the WM_IME_STARTCOMPOSITION message to that window. The DefWindowProc function processes this message by passing it to the default IME window.

See Also

DefWindowProc


WM_INITDIALOG

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.

Parameters

hwndFocus

Value of wParam. Identifies the control to receive the default keyboard focus. Windows assigns the default keyboard focus only if the dialog box procedure returns TRUE.

lInitParam

Value of lParam. Specifies additional initialization data. This data is passed to Windows as the lParamInit parameter in a call to the CreateDialogIndirectParam, CreateDialogParam, DialogBoxIndirectParam, or DialogBoxParam function used to create the dialog box. This parameter is zero if any other dialog box creation function is used.

Return Value

The dialog box procedure should return TRUE to direct Windows to set the keyboard focus to the control given by hwndFocus. Otherwise, it should return FALSE to prevent Windows from setting the default keyboard focus.

Remarks

The control to receive the default keyboard focus is always the first control in the dialog box that is visible, not disabled, and that has the WS_TABSTOP style. When the dialog box procedure returns TRUE, Windows checks the control to ensure that the procedure has not disabled it. If it has been disabled, Windows sets the keyboard focus to the next control that is visible, not disabled, and has the WS_TABSTOP.

An application can return FALSE only if it has set the keyboard focus to one of the controls of the dialog box.

See Also

CreateDialogIndirectParam, CreateDialogParam, DialogBoxIndirectParam, DialogBoxParam, SetFocus


WM_INITMENU

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.

Parameters

hmenuInit

Value of wParam. Identifies the menu to be initialized.

Return Value

If an application processes this message, it should return zero.

Remarks

A WM_INITMENU message is sent only when a menu is first accessed; only one WM_INITMENU message is generated for each access. For example, moving the mouse across several menu items while holding down the button does not generate new messages. WM_INITMENU does not provide information about menu items.

See Also

WM_INITMENUPOPUP


WM_INITMENUPOPUP

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.

Parameters

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.

Return Value

If an application processes this message, it should return zero.

See Also

WM_INITMENU


WM_INPUTLANGCHANGE  (preliminaryWindows 95)
WM_INPUTLANGCHANGE  (preliminary−Windows 95)

WM_INPUTLANGCHANGE
charset = wParam;
hkl = (HKL) lParam;

The WM_INPUTLANGCHANGE message is sent to the topmost affected window after a task's locale has been changed. It should be used to make any application-specific settings and passed on to the DefWindowProc function to be passed on to any children.

Parameters

charset

Value of wParam. Specifies the character set of the new keyboard layout.

hkl

Value of lParam. Identifies the new keyboard layout.

Return Value

An application should return nonzero if it processes this message.

See Also

DefWindowProc, WM_INPUTLANGCHANGEREQUEST


WM_INPUTLANGCHANGEREQUEST  (preliminaryWindows 95)
WM_INPUTLANGCHANGEREQUEST  (preliminary−Windows 95)

WM_INPUTLANGCHANGEREQUEST
hkl = (HKL) lParam;

The WM_INPUTLANGCHANGEREQUEST message is sent when the user chooses an input language, either with an input language change hotkey or from the system languages menu. An application can accept the change by passing the message to the DefWindowProc function or reject the change (and prevent it from taking place) by returning immediately.

Parameters

hkl

Value of lParam. Identifies the keyboard layout to switch to.

Return Value

The application should return nonzero if it processes this message. It should return zero to reject the change.

See Also

DefWindowProc, WM_INPUTLANGCHANGE


WM_KEYDOWN

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.

Parameters

nVirtKey

Value of wParam. Specifies the virtual-key code of the nonsystem key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is always 0 for a WM_KEYDOWN message.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is always 0 for a WM_KEYDOWN message.
Return Value

An application should return zero if it processes this message.

Default Action

If the F10 key is pressed, the DefWindowProc function sets an internal flag. When DefWindowProc receives the WM_KEYUP message, the function checks whether the internal flag is set and, if so, sends a WM_SYSCOMMAND message to the top-level window. The wParam parameter of the message is set to SC_KEYMENU.

Remarks

Because of the autorepeat feature, more than one WM_KEYDOWN message may be posted before a WM_KEYUP message is posted. The previous key state (bit 30) can be used to determine whether the WM_KEYDOWN message indicates the first down transition or a repeated down transition.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

DefWindowProc, WM_CHAR, WM_KEYUP, WM_SYSCOMMAND


WM_KEYUP

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.

Parameters

nVirtKey

Value of wParam. Specifies the virtual-key code of the nonsystem key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key. The repeat count is always one for a WM_KEYUP message.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is always 0 for a WM_KEYUP message.
30	Specifies the previous key state. The value is always 1 for a WM_KEYUP message.
31	Specifies the transition state. The value is always 1 for a WM_KEYUP message.
Return Value

An application should return zero if it processes this message.

Default Action

The DefWindowProc function sends a WM_SYSCOMMAND message to the top-level window if the F10 key or the ALT key was released. The wParam parameter of the message is set to SC_KEYMENU.

Remarks

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

DefWindowProc, WM_KEYDOWN, WM_SYSCOMMAND


WM_KILLFOCUS

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.

Parameters

hwndGetFocus

Value of wParam. Identifies the window that receives the keyboard focus (may be NULL).

Return Value

An application should return zero if it processes this message.

Remarks

If an application is displaying a caret, the caret should be destroyed at this point.

See Also

SetFocus, WM_SETFOCUS


WM_LBUTTONDBLCLK

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.

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Value

If an application processes this message, it should return zero.

Remarks

Only windows that have the CS_DBLCLKS style can receive WM_LBUTTONDBLCLK messages, which Windows generates whenever the user presses, releases, and again presses the left mouse button within the system's double-click time limit. Double-clicking the left mouse button actually generates four messages: WM_LBUTTONDOWN, WM_LBUTTONUP, WM_LBUTTONDBLCLK, and WM_LBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, GetDoubleClickTime, MAKEPOINTS, POINTS, SetCapture, SetDoubleClickTime, WM_LBUTTONDOWN, WM_LBUTTONUP


WM_LBUTTONDOWN

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.

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Value

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_LBUTTONDBLCLK, WM_LBUTTONUP


WM_LBUTTONUP

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.

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Value

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_LBUTTONDBLCLK, WM_LBUTTONDOWN


WM_MBUTTONDBLCLK

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.

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Value

If an application processes this message, it should return zero.

Remarks

Only windows that have the CS_DBLCLKS style can receive WM_MBUTTONDBLCLK messages, which Windows generates whenever the user presses, releases, and again presses the middle mouse button within the system's double-click time limit. Double-clicking the middle mouse button actually generates four messages: WM_MBUTTONDOWN, WM_MBUTTONUP, WM_MBUTTONDBLCLK, and WM_MBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, GetDoubleClickTime, MAKEPOINTS, POINTS, SetCapture, SetDoubleClickTime, WM_MBUTTONDOWN, WM_MBUTTONUP


WM_MBUTTONDOWN

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.

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Return Value

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_MBUTTONDBLCLK, WM_MBUTTONUP


WM_MBUTTONUP

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.

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_MBUTTONDBLCLK, WM_MBUTTONDOWN


WM_MDIACTIVATE

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.

Parameters

In messages sent to an MDI client window:

hwndChildAct

Value of wParam. Identifies the MDI child window to be activated.

In messages received by an MDI child window:

hwndChildDeact

Value of wParam. Identifies the MDI child window being deactivated.

hwndChildAct

Value of lParam. Identifies the MDI child window being activated.

Return Value

If an application sends this message to an MDI client window, the return value is zero. An MDI child window should return zero if it processes this message.

Remarks

An MDI child window is activated independently of the MDI frame window. When the frame window becomes active, the child window last activated by using the WM_MDIACTIVATE message receives the WM_NCACTIVATE message to draw an active window frame and title bar; the child window does not receive another WM_MDIACTIVATE message.

See Also

WM_MDIGETACTIVE, WM_MDINEXT, WM_NCACTIVATE


WM_MDICASCADE

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.

Parameters

fuCascade

Value of wParam. Specifies a cascade flag. The only flag currently available, MDITILE_SKIPDISABLED, prevents disabled MDI child windows from being cascaded.

Return Value

If the message succeeds, the return value is TRUE.

If the message fails, the return value is FALSE.

See Also

WM_MDIICONARRANGE, WM_MDITILE


WM_MDICREATE

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.

Parameters

lpmdic

Points to an MDICREATESTRUCT structure containing information that Windows uses to create the MDI child window.

Return Value

If the message succeeds, the return value is the handle of the new child window.

If the message fails, the return value is NULL.

Remarks

The MDI child window is created with the style bits WS_CHILD, WS_CLIPSIBLINGS, WS_CLIPCHILDREN, WS_SYSMENU, WS_CAPTION, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX, plus additional style bits specified in the MDICREATESTRUCT structure to which the lpmdic parameter points. Windows adds the title of the new child window to the Window menu of the frame window. An application should use this message to create all child windows of the client window.

If an MDI client window receives any message that changes the activation of its child windows while the active child window is maximized, Windows restores the active child window and maximizes the newly activated child window.

When an MDI child window is created, Windows sends the WM_CREATE message to the window. The lParam parameter of the WM_CREATE message contains a pointer to a CREATESTRUCT structure. The lpCreateParams member of this structure contains a pointer to the MDICREATESTRUCT structure passed with the WM_MDICREATE message that created the MDI child window.

An application should not send a second WM_MDICREATE message while a WM_MDICREATE message is still being processed. For example, it should not send a WM_MDICREATE message while an MDI child window is processing its WM_MDICREATE message.

See Also

CreateMDIWindow, CREATESTRUCT, MDICREATESTRUCT, WM_CREATE, WM_MDIDESTROY


WM_MDIDESTROY

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.

Parameters

hwndChild

Value of wParam. Identifies the MDI child window to be closed.

Return Value

This message always returns zero.

Remarks

This message removes the title of the MDI child window from the MDI frame window and deactivates the child window. An application should use this message to close all MDI child windows.

If an MDI client window receives a message that changes the activation of its child windows and the active MDI child window is maximized, Windows restores the active child window and maximizes the newly activated child window.

See Also

WM_MDICREATE


WM_MDIGETACTIVE

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.

Parameters

lpfMaximized

Value of lparam. This is an optional pointer to a maximized state flag variable. If lpfMaximized is non-NULL, the BOOL it points to is set to indicate the maximized state of the MDI child window. TRUE indicates that the window is maximized, FALSE indicates that it is not. This is equivalent to the indication supplied by the high-order word of the return value of the WM_MDIGETACTIVE message under Windows version 3.x. If lpfMaximized is NULL, the parameter is ignored.

Return Value

The return value is the handle of the active MDI child window.

Remarks

Note carefully a change in how this message indicates maximization. In Windows version 3.x, the message return value includes a flag indicating whether the MDI child window is maximized. In the Win32 application programming interface (API), the return value does not include this flag. In Win32, the MDI child window's maximized state is indicated by setting a BOOL variable via the optional parameter in lParam, lpfMaximized.


WM_MDIICONARRANGE

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

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.

Parameters

hwndMax

Value of wParam. Identifies the MDI child window to be maximized.

Return Value

The return value is always zero.

Remarks

If an MDI client window receives any message that changes the activation of its child windows while the currently active MDI child window is maximized, Windows restores the active child window and maximizes the newly activated child window.

See Also

WM_MDIRESTORE


WM_MDINEXT

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.

Parameters

hwndChild

Value of wParam. Identifies the MDI child window. Windows activates the child window that is immediately before or after the given child window, depending on the value of the fNext parameter. If the hwndChild parameter is NULL, Windows activates the child window that is immediately before or after the currently active child window.

fNext

Value of lParam. If this parameter is zero, Windows activates the next MDI child window and places the child window identified by the hwndChild parameter behind all other child windows. If this parameter is nonzero, Windows activates the previous child window, placing it in front of the child window identified by hwndChild.

Return Value

The return value is always zero.

Remarks

If an MDI client window receives any message that changes the activation of its child windows while the active MDI child window is maximized, Windows restores the active child window and maximizes the newly activated child window.

See Also

WM_MDIACTIVATE, WM_MDIGETACTIVE


WM_MDIREFRESHMENU

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.

Return Value

If the message succeeds, the return value is the handle of the frame window menu.

If the message fails, the return value is NULL.

Remarks

After sending this message, an application must call the DrawMenuBar function to update the menu bar.

See Also

DrawMenuBar, WM_MDISETMENU


WM_MDIRESTORE

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.

Parameters

hwndRes

Value of wParam. Identifies the MDI child window to be restored.

Return Value

The return value is always zero.

See Also

WM_MDIMAXIMIZE


WM_MDISETMENU

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.

Parameters

hmenuFrame

Value of wParam. Identifies the new frame window menu. If this parameter is NULL, the frame window menu is not changed.

hmenuWindow

Value of lParam. Identifies the new Window menu. If this parameter is NULL, the Window menu is not changed.

Return Value

If the message succeeds, the return value is the handle of the old frame window menu.

If the message fails, the return value is zero.

Remarks

After sending this message, an application must call the DrawMenuBar function to update the menu bar.

If this message replaces the Window menu, the MDI child window menu items are removed from the previous Window menu and added to the new Window menu.

If an MDI child window is maximized and this message replaces the MDI frame window menu, the System menu icon and restore icon are removed from the previous frame window menu and added to the new frame window menu.

See Also

DrawMenuBar, WM_MDIREFRESHMENU


WM_MDITILE

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.

Parameters

fuTile

Specifies a tiling flag. This parameter can be one of the following values:

Value	Meaning
MDITILE_HORIZONTAL	Tiles MDI child windows so that they are wide rather than tall.
MDITILE_SKIPDISABLED	Prevents disabled MDI child windows from being tiled.
MDITILE_VERTICAL	Tiles MDI child windows so that they are tall rather than wide.
Return Value

If the message succeeds, the return value is TRUE.

If the message fails, the return value is FALSE.

See Also

WM_MDICASCADE, WM_MDIICONARRANGE


WM_MEASUREITEM

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.

Parameters

idCtl

Value of wParam. Contains the value of the CtlID member of the MEASUREITEMSTRUCT structure pointed to by the lpmis parameter. This value identifies the control that sent the WM_MEASUREITEM message.

If the value is zero, the message was sent by a menu. If the value is nonzero, the message was sent by a combo box or by a list box. If the value is nonzero, and the value of the itemID member of the MEASUREITEMSTRUCT pointed to by lpmis is (UINT) −1, the message was sent by a combo edit field.

lpmis

Value of lParam. Points to a MEASUREITEMSTRUCT structure that contains the dimensions of the owner-drawn control or menu item.

Return Value

If an application processes this message, it should return TRUE.

Remarks

When the owner window receives the WM_MEASUREITEM message, the owner fills in the MEASUREITEMSTRUCT structure pointed to by the lParam parameter of the message and returns; this informs Windows of the dimensions of the control. If a list box or combo box is created with the LBS_OWNERDRAWVARIABLE or CBS_OWNERDRAWVARIABLE style, this message is sent to the owner for each item in the control; otherwise, this message is sent once.

Windows sends the WM_MEASUREITEM message to the owner window of combo boxes and list boxes created with the OWNERDRAWFIXED style before sending the WM_INITDIALOG message. As a result, when the owner receives this message, Windows has not yet determined the height and width of the font used in the control; function calls and calculations requiring these values should occur in the main function of the application or library.

See Also

MEASUREITEMSTRUCT, WM_INITDIALOG


WM_MENUCHAR

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.

Parameters

chUser

Value of the low-order word of wParam. Specifies the ASCII character that corresponds to the key the user pressed.

fuFlag

Value of the high-order word of wParam. Specifies the type of the active menu. This parameter can be one of the following values:

Value	Meaning
MF_POPUP	Pop-up menu
MF_SYSMENU	System menu
hmenu

Value of lParam. Identifies the active menu.

Return Value

An application that processes this message should return one of the following values in the high-order word of the return value:

Value	Meaning
0	Informs Windows that it should discard the character the user pressed and create a short beep on the system speaker.
1	Informs Windows that it should close the active menu.
2	Informs Windows that the low-order word of the return value specifies the zero-based relative position of a menu item. This item is selected by Windows.
Remarks

The low-order word is ignored if the high-order word contains 0 or 1. An application should process this message when an accelerator is used to select a menu item that displays a bitmap.


WM_MENUSELECT

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

The WM_MENUSELECT message is sent to a menu's owner window when the user selects a menu item.

Parameters

uItem

Value of the low-order word of wParam. If the selected item is a command item, this parameter contains the identifier of the menu item. If the selected item 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) 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.

Return Value

If an application processes this message, it should return zero.

Remarks

If the fuFlags parameter contains 0xFFFF and the hmenu parameter contains NULL, Windows has closed the menu 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.

See Also

GetSubMenu


WM_MOUSEACTIVATE

WM_MOUSEACTIVATE

hwndTopLevel = (HWND) wParam;       // handle of top-level parent

nHittest = (INT) LOWORD(lParam);    // hit-test value

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.

Parameters

hwndTopLevel

Value of wParam. Identifies the top-level parent window of the window being activated.

nHittest

Value of the low-order word of lParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

uMsg

Value of the high-order word of lParam. Specifies the identifier of the mouse message generated when the user pressed a mouse button. The mouse message is either discarded or posted to the window, depending on the return value.

Return Value

The return value specifies whether the window should be activated and whether the identifier of the mouse message should be discarded. It must be one of the following values:

Value	Meaning
MA_ACTIVATE	Activates the window, and does not discard the mouse message.
MA_ACTIVATEANDEAT	Activates the window, and discards the mouse message.
MA_NOACTIVATE	Does not activate the window, and does not discard the mouse message.
MA_NOACTIVATEANDEAT	Does not activate the window, but discards the mouse message.
Default Action

The DefWindowProc function passes the message to a child window's parent window before any processing occurs. The parent window determines whether to activate the child window. If it activates the child window, the parent window should return TRUE to prevent the system from processing the message further.

See Also

DefWindowProc, WM_NCHITTEST


WM_MOUSEMOVE

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.

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Remarks

The MAKEPOINTS macro can be used to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture


WM_MOVE

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.

Parameters

xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the upper-left corner of the client area of the window.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the upper-left corner of the client area of the window.

Return Value

If an application processes this message, it should return zero.

Remarks

The xPos and yPos parameters are given in screen coordinates for overlapped and pop-up windows and in parent-client coordinates for child windows.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

MAKEPOINTS, POINTS


WM_MOVING  (preliminaryWindows 95)
WM_MOVING  [image]  (preliminary−Windows 95)

fwSide = wParam;	// edge of window to be moved

lprc = (LPRECT) lParam;	// screen coordinates of drag rectangle

The WM_MOVING message is sent to a window that the user is moving. By processing this message, an application can monitor the size and position of the drag rectangle and, if needed, change its size or position.

Parameters

fwSide

Value of wParam. Indicates which edge of the window is being moved. This parameter can be a combination of the following values:

Value	Meaning
WMSZ_BOTTOM	Bottom edge
WMSZ_BOTTOMLEFT	Bottom-left corner
WMSZ_BOTTOMRIGHT	Bottom-right corner
WMSZ_LEFT	Left edge
WMSZ_RIGHT	Right edge
WMSZ_TOP	Top edge
WMSZ_TOPLEFT	Top-left corner
WMSZ_TOPRIGHT	Top-right corner
lprc

Value of lParam. Address of a RECT structure with the screen coordinates of the drag rectangle. To change the size or position of the drag rectangle, an application must change the members of this structure.

Return Value

An application should return TRUE if it processes this message.

See Also

RECT, WM_MOVE, WM_SIZING


WM_NCACTIVATE

WM_NCACTIVATE

fActive = (BOOL) wParam;	// new state of the title bar or icon

The WM_NCACTIVATE message is sent to a window when its nonclient area needs to be changed to indicate an active or inactive state.

Parameters

fActive

Value of wParam. Specifies when a title bar or icon needs to be changed to indicate an active or inactive state. If an active title bar or icon is to be drawn, the fActive parameter is TRUE. It is FALSE for an inactive title bar or icon.

Return Value

When the fActive parameter is FALSE, an application should return TRUE to indicate that Windows should proceed with the default processing, or it should return FALSE to prevent the title bar or icon from being deactivated. When fActive is TRUE, the return value is ignored.

Default Action

The DefWindowProc function draws the title bar or icon title in its active colors when the fActive parameter is TRUE and in its inactive colors when fActive is FALSE.

See Also

DefWindowProc


WM_NCCALCSIZE

WM_NCCALCSIZE

fCalcValidRects = (BOOL) wParam;        // valid area flag

lpncsp = (LPNCCALCSIZE_PARAMS) lParam;  // points to size calculation data

   or

lpncsp = (LPRECT) lParam;               // points to new window coordinates

The WM_NCCALCSIZE message is sent when the size and position of a window's client area must be calculated. By processing this message, an application can control the content of the window's client area when the size or position of the window changes.

Parameters

fCalcValidRects

Value of wParam. A Boolean value that, if TRUE, specifies that the application should indicate which part of the client area contains valid information. The operating system copies the valid information to the specified area within the new client area. Also, if this parameter is TRUE, lParam points to an NCCALCSIZE structure.

If this parameter is FALSE, the application does not need to indicate the valid part of the client area. Also, if this parameter is FALSE, lParam points to a RECT structure.

lpncsp

Value of lParam.

If wParam  is TRUE, lParam points to an NCCALCSIZE_PARAMS structure that contains information an application can use to calculate the new size and position of the client rectangle.

If wParam  is FALSE, lParam points to a RECT structure that contains the new coordinates of the window that has been moved or resized. This is equivalent to rgrc[0] of an NCCALCSIZE_PARAMS structure.

Return Value

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

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.

Parameters

lpcs

Value of wParam. Points to the CREATESTRUCT structure for the window.

Return Value

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

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.

Return Value

If an application processes this message, it should return zero.

Remarks

This message frees any memory internally allocated for the window.

See Also

DestroyWindow, WM_DESTROY, WM_NCCREATE


WM_NCHITTEST

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.

Parameters

xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the screen.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the screen.

Return Value

The return value of the DefWindowProc function is one of the following values, indicating the position of the cursor hot spot:

Value	Location of hot spot
HTBORDER	In the border of a window that does not have a sizing border
HTBOTTOM	In the lower horizontal border of a window
HTBOTTOMLEFT	In the lower-left corner of a window border
HTBOTTOMRIGHT	In the lower-right corner of a window border
HTCAPTION	In a title bar
HTCLIENT	In a client area
HTERROR	On the screen background or on a dividing line between windows (same as HTNOWHERE, except that the DefWindowProc function produces a system beep to indicate an error)
HTGROWBOX	In a size box (same as HTSIZE)
HTHSCROLL	In a horizontal scroll bar
HTLEFT	In the left border of a window
HTMENU	In a menu
HTNOWHERE	On the screen background or on a dividing line between windows
HTREDUCE	In a Minimize button
HTRIGHT	In the right border of a window
HTSIZE	In a size box (same as HTGROWBOX)
HTSYSMENU	In a System menu or in a Close button in a child window
HTTOP	In the upper horizontal border of a window
HTTOPLEFT	In the upper-left corner of a window border
HTTOPRIGHT	In the upper right corner of a window border
HTTRANSPARENT	In a window currently covered by another window
HTVSCROLL	In the vertical scroll bar
HTZOOM	In a Maximize button
Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, GetCapture, MAKEPOINTS, POINTS


WM_NCLBUTTONDBLCLK

WM_NCLBUTTONDBLCLK

nHittest = (INT) wParam;    // hit-test value

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.

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Value

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function tests the given point to find out the location of the cursor and performs the appropriate action. If appropriate, DefWindowProc sends the WM_SYSCOMMAND message to the window.

Remarks

A window need not have the CS_DBLCLKS style to receive WM_NCLBUTTONDBLCLK messages.

Windows generates a WM_NCLBUTTONDBLCLK message when the user presses, releases, and again presses the left mouse button within the system's double-click time limit. Double-clicking the left mouse button actually generates four messages: WM_NCLBUTTONDOWN, WM_NCLBUTTONUP, WM_NCLBUTTONDBLCLK, and WM_NCLBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCLBUTTONDOWN, WM_NCLBUTTONUP, WM_SYSCOMMAND


WM_NCLBUTTONDOWN

WM_NCLBUTTONDOWN

nHittest = (INT) wParam;    // hit-test value

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.

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Value

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function tests the given point to find out the location of the cursor and performs the appropriate action. If appropriate, DefWindowProc sends the WM_SYSCOMMAND message to the window.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCLBUTTONDBLCLK, WM_NCLBUTTONUP, WM_SYSCOMMAND


WM_NCLBUTTONUP

WM_NCLBUTTONUP

nHittest = (INT) wParam;    // hit-test value

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.

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Value

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function tests the given point to find out the location of the cursor and performs the appropriate action. If appropriate, DefWindowProc sends the WM_SYSCOMMAND message to the window.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCLBUTTONDBLCLK, WM_NCLBUTTONDOWN, WM_SYSCOMMAND


WM_NCMBUTTONDBLCLK

WM_NCMBUTTONDBLCLK

nHittest = (INT) wParam;    // hit-test value

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.

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Value

If an application processes this message, it should return zero.

Remarks

A window need not have the CS_DBLCLKS style to receive WM_NCMBUTTONDBLCLK messages.

Windows generates a WM_NCMBUTTONDBLCLK message when the user presses, releases, and again presses the middle mouse button within the system's double-click time limit. Double-clicking the middle mouse button actually generates four messages: WM_NCMBUTTONDOWN, WM_NCMBUTTONUP, WM_NCMBUTTONDBLCLK, and WM_NCMBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCMBUTTONDOWN, WM_NCMBUTTONUP, WM_SYSCOMMAND


WM_NCMBUTTONDOWN

WM_NCMBUTTONDOWN

nHittest = (INT) wParam;    // hit-test value

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.

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Value

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCMBUTTONDBLCLK, WM_NCMBUTTONUP, WM_SYSCOMMAND


WM_NCMBUTTONUP

WM_NCMBUTTONUP

nHittest = (INT) wParam;    // hit-test value

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.

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Value

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCMBUTTONDBLCLK, WM_NCMBUTTONDOWN, WM_SYSCOMMAND


WM_NCMOUSEMOVE

WM_NCMOUSEMOVE

nHittest = (INT) wParam;    // hit-test value

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.

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Value

If an application processes this message, it should return zero.

Remarks

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_SYSCOMMAND


WM_NCPAINT

WM_NCPAINT

hrgn = (HRGN) wParam;   // handle of update region

An application sends the WM_NCPAINT message to a window when its frame must be painted.

Parameters

hrgn

Value of wParam. Identifies the update region of the window. The update region is clipped to the window frame.

Return Value

An application should return zero if it processes this message.

Remarks

The DefWindowProc function paints the window frame.

An application can intercept this message and paint its own custom window frame. The clipping region for a window is always rectangular, even if the shape of the frame is altered.

See Also

DefWindowProc, GetWindowDC, WM_PAINT


WM_NCRBUTTONDBLCLK

WM_NCRBUTTONDBLCLK

nHittest = (INT) wParam;    // hit-test value

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.

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Value

If an application processes this message, it should return zero.

Remarks

A window need not have the CS_DBLCLKS style to receive WM_NCRBUTTONDBLCLK messages.

Windows generates a WM_NCRBUTTONDBLCLK message when the user presses, releases, and again presses the right mouse button within the system's double-click time limit. Double-clicking the right mouse button actually generates four messages: WM_NCRBUTTONDOWN, WM_NCRBUTTONUP, WM_NCRBUTTONDBLCLK, and WM_NCRBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCRBUTTONDOWN, WM_NCRBUTTONUP, WM_SYSCOMMAND


WM_NCRBUTTONDOWN

WM_NCRBUTTONDOWN

nHittest = (INT) wParam;    // hit-test value

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.

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Value

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONUP, WM_SYSCOMMAND


WM_NCRBUTTONUP

WM_NCRBUTTONUP

nHittest = (INT) wParam;    // hit-test value

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.

Parameters

nHittest

Value of wParam. Specifies the hit-test value returned by the DefWindowProc function as a result of processing the WM_NCHITTEST message. For a list of hit-test values, see WM_NCHITTEST.

pts

Value of lParam. Specifies a POINTS structure that contains the x- and y-coordinates of the cursor. The coordinates are relative to the upper-left corner of the screen.

Return Value

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

If it is appropriate to do so, the system sends the WM_SYSCOMMAND message to the window.

See Also

DefWindowProc, MAKEPOINTS, POINTS, WM_NCHITTEST, WM_NCRBUTTONDBLCLK, WM_NCRBUTTONDOWN, WM_SYSCOMMAND


WM_NEXTDLGCTL

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.

Parameters

wCtlFocus

Value of wParam. If the fHandle parameter is TRUE, the wCtlFocus parameter identifies the control that receives the focus. If fHandle is FALSE, wCtlFocus is a flag that indicates whether the next or previous control with the WS_TABSTOP style receives the focus. If wCtlFocus is zero, the next control receives the focus; otherwise, the previous control with the WS_TABSTOP style receives the focus.

fHandle

Value of lParam. Contains a flag that indicates how Windows uses the wCtlFocus parameter. If the fHandle parameter is TRUE, wCtlFocus is a handle associated with the control that receives the focus; otherwise, wCtlFocus is a flag that indicates whether the next or previous control with the WS_TABSTOP style receives the focus.

Return Value

An application should return zero if it processes this message.

Remarks

The effect of this message differs from that of the SetFocus function because WM_NEXTDLGCTL modifies the border around the control.

Do not use the SendMessage function to send a WM_NEXTDLGCTL message if your application will concurrently process other messages that set the focus. Use the PostMessage function instead.

See Also

PostMessage, SendMessage, SetFocus


WM_NOTIFY  (preliminaryWindows NT)
WM_NOTIFY  (preliminary−Windows NT)

WM_NOTIFY

idCtrl = (int) wParam;

pnmh = (LPNMHDR) lParam;

The WM_NOTIFY message informs the parent window of a control that an event has occurred in the control or that the control requires some kind of information.

Parameters

idCtrl

Identifier of the control sending the message.

pnmh

Pointer to an NMHDR structure that contains the notification code and additional information. For some notification messages, this parameter points to a larger structure that has the NMHDR structure as its first member.

Return Value

The return value is ignored except for notification messages that specify otherwise.


WM_NOTIFYFORMAT  (preliminaryWindowsNT)
WM_NOTIFYFORMAT  (preliminary−Windows NT)

hwndFrom = (HWND) wParam;        // handle of the window sending this message

Command =  lParam;               // command value specifying the nature of this message

Common controls, custom controls, and their parent windows use the WM_NOTIFYFORMAT message to determine whether the control should use ANSI or Unicode structures in the WM_NOTIFY notification messages that the control uses to communicate with its parent window. WM_NOTIFYFORMAT messages are sent from a control to its parent window, and from the parent window to the control.

Parameters

hwndFrom

Value of wParam. Handle of the window that is sending the WM_NOTIFYFORMAT message. If Command is NF_QUERY, hwndFrom is the handle of a control. If Command is NF_REQUERY, this is the handle of the parent window of a control.

Command

Value of lParam. A command value that specifies the nature of the WM_NOTIFYFORMAT message. The following values are defined:

Value	Meaning
NF_QUERY	The message is a query to determine whether ANSI or Unicode structures should be used in WM_NOTIFY messages. This command is sent from a control to its parent window. This command is sent during the creation of a control, and in response to an NF_REQUERY command.
NF_REQUERY	The message is a request that a control send an NF_QUERY form of this message to its parent window. This command is sent from a control's parent window to the control. The parent window is asking the control to requery it about the type of structures to use in WM_NOTIFY messages.
Return Value

The return value is one of the following :

Value	Meaning
NFR_ANSI	ANSI structures should be used in WM_NOTIFY messages sent by the control.
NFR_UNICODE	Unicode structures should be used in WM_NOTIFY messages sent by the control.
0	An error occurred.
If Command is NF_REQUERY, the return value is the result of the requery operation.

Remarks

When a common control is created, the control sends a WM_NOTIFYFORMAT message to its parent window to determine the type of structures to use in WM_NOTIFY messages. If the parent window does not handle this message, the DefWindowProc function responds according to the type of the parent window. That is, if the parent window is a Unicode window, DefWindowProc returns NFR_UNICODE, and if the parent window is an ANSI window, DefWindowProc returns NFR_ANSI. If the parent window is a dialog box and does not handle this message, the DefDlgProc function similarly responds according to the type of the dialog box (Unicode or ANSI).

A parent window can change the type of structures a common control uses in WM_NOTIFY messages by setting lParam to NF_REQUERY and sending a WM_NOTIFYFORMAT message to the control. This causes the control to send an NF_QUERY form of the WM_NOTIFYFORMAT message to the parent window.

See Also

DefDlgProc, DefWindowProc, WM_NOTIFY


WM_PAINT

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.

Return Value

An application should return zero if it processes this message.

Remarks

The DefWindowProc function validates the update region. The function may also send the WM_NCPAINT message to the window procedure if the window frame must be painted and send the WM_ERASEBKGND message if the window background must be erased.

The system sends this message when there are no other messages in the application's message queue. DispatchMessage determines where to send the message; GetMessage determines which message to dispatch. GetMessage returns the WM_PAINT message when there are no other messages in the application's message queue, and DispatchMessage sends the message to the appropriate window procedure.

A window may receive internal paint messages as a result of calling RedrawWindow with the RDW_INTERNALPAINT flag set. In this case, the window may not have an update region. An application should call the GetUpdateRect function to determine whether the window has an update region. If GetUpdateRect returns zero, the application should not call the BeginPaint and EndPaint functions.

An application must check for any necessary internal painting by looking at its internal data structures for each WM_PAINT message, because a WM_PAINT message may have been caused by both a non-NULL update region and a call to RedrawWindow with the RDW_INTERNALPAINT flag set.

Windows sends an internal WM_PAINT message only once. After an internal WM_PAINT message is returned from GetMessage or PeekMessage or is sent to a window by UpdateWindow, Windows does not post or send further WM_PAINT messages until the window is invalidated or until RedrawWindow is called again with the RDW_INTERNALPAINT flag set.

See Also

BeginPaint, DefWindowProc, DispatchMessage, EndPaint, GetMessage, GetUpdateRect, PeekMessage, RedrawWindow, UpdateWindow, WM_ERASEBKGND, WM_NCPAINT


WM_PAINTCLIPBOARD

WM_PAINTCLIPBOARD

hwndViewer = (HWND) wParam;     // handle of clipboard viewer window

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.

Parameters

hwndViewer

Value of wParam. Identifies the clipboard viewer window.

hglbPs

Value of lParam. Identifies a global DDESHARE object that contains a PAINTSTRUCT structure. The structure defines the part of the client area to paint.

Return Value

If an application processes this message, it should return zero.

Remarks

To determine whether the entire client area or just a portion of it needs repainting, the clipboard owner must compare the dimensions of the drawing area given in the rcpaint member of PAINTSTRUCT to the dimensions given in the most recent WM_SIZECLIPBOARD message.

The clipboard owner must use the GlobalLock function to lock the memory that contains the PAINTSTRUCT structure. Before returning, the clipboard owner must unlock that memory by using the GlobalUnlock function.

See Also

GlobalLock, GlobalUnlock, PAINTSTRUCT, WM_SIZECLIPBOARD


WM_PAINTICON

WM_PAINTICON

The WM_PAINTICON message is sent to a minimized window when the icon is to be painted but only if the application is written for Windows 3.x. A window receives this message only if a class icon is defined for the window; otherwise, WM_PAINT is sent instead.

Parameters

This message has no parameters.

Return Value

An application should return zero if it processes this message.

Remarks

The DefWindowProc function draws the class icon. For compatibility with Windows 3.x, wParam is TRUE. However, this value has no significance.

See Also

DefWindowProc, WM_ICONERASEBKGND, WM_PAINT


WM_PALETTECHANGED

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 that uses a color palette but does not have the keyboard focus to realize its logical palette and update its client area.

Parameters

hwndPalChg

Value of wParam. Identifies the window that caused the system palette to change.

Remarks

This message must be sent to all top-level and overlapped windows, including the one that changed the system palette. If any child windows use a color palette, this message must be passed on to them as well.

To avoid creating an infinite loop, a window that receives this message must not realize its palette, unless it determines that wParam does not contain its own window handle.

See Also

WM_PALETTEISCHANGING, WM_QUERYNEWPALETTE


WM_PALETTEISCHANGING

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.

Parameters

hwndRealize

Value of wParam. Identifies the window that is going to realize its logical palette.

Return Value

If an application processes this message, it should return zero.

Remarks

The application changing its palette does not wait for acknowledgment of this message before changing the palette and sending the WM_PALETTECHANGED message. As a result, the palette may already be changed by the time an application receives this message.

If the application either ignores or fails to process this message and a second application realizes its palette while the first is using palette indices, there is a strong possibility that the user will see unexpected colors during subsequent drawing operations.

See Also

WM_PALETTECHANGED, WM_QUERYNEWPALETTE


WM_PARENTNOTIFY

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.

Parameters

fwEvent

Value of the low-order word of wParam. Specifies the event for which the parent is being notified. This parameter can be one of the following values:

Value	Meaning
WM_CREATE	The child window is being created.
WM_DESTROY	The child window is being destroyed.
WM_LBUTTONDOWN	The user has placed the cursor over the child window and has clicked the left mouse button.
WM_MBUTTONDOWN	The user has placed the cursor over the child window and has clicked the middle mouse button.
WM_RBUTTONDOWN	The user has placed the cursor over the child window and has clicked the right mouse button.
idChild

Value of the high-order word of wParam. If the fwEvent parameter is the WM_CREATE or WM_DESTROY value, idChild specifies the identifier of the child window. Otherwise, idChild is undefined.

lValue

Contains the handle of the child window, if the fwEvent parameter is the WM_CREATE or WM_DESTROY value; otherwise, lValue contains the x- and y-coordinates of the cursor. The x-coordinate is in the low-order word and the y-coordinate is in the high-order word.

Return Value

If an application processes this message, it should return zero.

Remarks

This message is also sent to all ancestor windows of the child window, including the top-level window.

All child windows, except those that have the WS_EX_NOPARENTNOTIFY extended window style, send this message to their parent windows. By default, child windows in a dialog box have the WS_EX_NOPARENTNOTIFY style, unless the CreateWindowEx function is called to create the child window without this style.

See Also

CreateWindow, CreateWindowEx, WM_CREATE, WM_DESTROY, WM_LBUTTONDOWN, WM_MBUTTONDOWN, WM_RBUTTONDOWN


WM_PASTE

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 content of the clipboard to the edit control at the current caret position. Data is inserted only if the clipboard contains data in CF_TEXT format.

Parameters

This message has no parameters.

Return Value

This message does not return a value.

Remarks

When sent to a combo box, the WM_PASTE message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

WM_CLEAR, WM_COPY, WM_CUT


WM_POWER

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 suspended mode.

Windows 95: For Windows 95 applications, The WM_POWER message is not supported. It is provided to simplify porting of 16-bit Windows-based applications. Win32-based applications for Windows 95 should use the WM_POWERBROADCAST message.

Parameters

fwPowerEvt

Value of wParam. Specifies a power-event notification message. This parameter can be one of the following values:

Value	Meaning
PWR_CRITICALRESUME	Indicates that the system is resuming operation after entering suspended mode without first sending a PWR_SUSPENDREQUEST notification message to the application. An application should perform any necessary recovery actions.
PWR_SUSPENDREQUEST	Indicates that the system is about to enter suspended mode.
PWR_SUSPENDRESUME	Indicates that the system is resuming operation after having entered suspended mode normally — that is, the system sent a PWR_SUSPENDREQUEST notification message to the application before the system was suspended. An application should perform any necessary recovery actions.
Return Value

The value an application returns depends on the value of the wParam parameter. If wParam is PWR_SUSPENDREQUEST, the return value is PWR_FAIL to prevent the system from entering the suspended state; otherwise, it is PWR_OK. If wParam is PWR_SUSPENDRESUME or PWR_CRITICALRESUME, the return value is zero.

Remarks

This message is sent only to an application that is running on a system that conforms to the Advanced Power Management (APM) basic input/output system (BIOS) specification. The message is sent by the power-management driver to each window returned by the EnumWindows function.

The suspended mode is the state in which the greatest amount of power savings occurs, but all operational data and parameters are preserved. Random-access memory (RAM) contents are preserved, but many devices are likely to be turned off.

See Also

EnumWindows


WM_POWERBROADCAST  (preliminaryWindows 95)
WM_POWERBROADCAST  [image]  (preliminary−Windows 95)

dwPowerEvent = (DWORD) wParam;
dwData = (DWORD) lParam;

The WM_POWERBROADCAST message is sent to an application to notify it of power-management events.

Windows NT: For Windows NT applications, use WM_POWER.

Parameters

dwPowerEvent

Event notification message. This parameter can be one of the following values:

Value	Meaning
PB_APMPOWERSTATUSCHANGED	Power status has changed.
PB_APMQUERYSTANDBY	Request for permission to standby.
PB_APMQUERYSTANDBYFAILED	Standby request denied.
PB_APMQUERYSUSPEND	Request for permission to suspend.
PB_APMQUERYSUSPENDFAILED	Suspension request denied.
PB_APMRESUMECRITICAL	Operation resuming after critical suspension.
PB_APMRESUMESTANDBY	Operation resuming after standby.
PB_APMRESUMESUSPEND	Operation resuming after suspension.
PB_APMSTANDBY	System is changing to standby.
PB_APMSUSPEND	System is suspending operation.
dwData

Function-specific data. For most messages, this parameter is reserved and not used.

Return Value

Returns TRUE if successful or FALSE otherwise.


WM_PRINT  (preliminaryWindows 95)
WM_PRINT  [image]  (preliminary−Windows 95)

WM_PRINT

hdc = (HDC) wParam;

uFlags = lParam;

The WM_PRINT message is sent to a window to request that it draw itself in the specified device context, most commonly in a printer device context.

Parameters

hdc

Identifies the device context to draw in.

uFlags

Specifies the drawing options. This parameter can be one or more of these flags:

Value	Meaning
PRF_CHECKVISIBLE	Draw the window only if it is visible.
PRF_CHILDREN	Draw all visible children windows.
PRF_CLIENT	Draw the client area of the window.
PRF_ERASEBKGND	Erase the background before drawing the window.
PRF_NONCLIENT	Draw the nonclient area of the window.
PRF_OWNED	Draw all owned windows.
Remarks

The DefWindowProc function processes this message based on which drawing option is specified: if PRF_CHECKVISIBLE is specified and the window is not visible, do nothing, if PRF_NONCLIENT is specified, draw the nonclient area in the given device context, if PRF_ERASEBKGND is specified, send the window a WM_ERASEBKGND message, if PRF_PRINTCLIENT is specified, send the window a WM_PRINTCLIENT message, if PRF_PRINTCHILDREN is set, send each visible child window a WM_PRINT message, if PRF_OWNED is set, send each visible owned window a WM_PRINT message.

See Also

DefWindowProc, WM_ERASEBKGND, WM_PRINTCLIENT


WM_PRINTCLIENT  (preliminaryWindows NT)
WM_PRINTCLIENT

WM_PRINTCLIENT

hdc = (HDC) wParam;

uFlags = lParam;

The WM_PRINTCLIENT message is sent to a window to request that it draw its client area in the specified device context, most commonly in a printer device context.

Parameters

hdc

Identifies the device context to draw in.

uFlags

Specifies drawing options. This parameter can be one or more of these flags:

Value	Meaning
PRF_CHECKVISIBLE	Draw the window only if it is visible.
PRF_CHILDREN	Draw all visible children windows.
PRF_CLIENT	Draw the client area of the window.
PRF_ERASEBKGND	Erase the background before drawing the window.
PRF_NONCLIENT	Draw the nonclient area of the window.
PRF_OWNED	Draw all owned windows.
Remarks

A window can process this message in much the same manner as WM_PAINT, except that BeginPaint and EndPaint need not be called (a device context is provided), and the window should draw its entire client area rather than just the invalid region.

Windows that can be used anywhere in the system, such as controls, should process this message. It is probably worthwhile for other windows to process this message as well because it is relatively easy to implement.

See Also

BeginPaint, EndPaint, WM_PAINT


WM_QUERYDRAGICON

WM_QUERYDRAGICON

The WM_QUERYDRAGICON message is sent to a minimized (iconic) window. The window is about to be dragged by the user but does not have an icon defined for its class. An application can return the handle of an icon or cursor. The system displays this cursor or icon while the user drags the icon.

Parameters

This message has no parameters.

Return Value

An application should return the handle of a cursor or icon that Windows is to display while the user drags the icon. The cursor or icon must be compatible with the display driver's resolution. If the application returns NULL, the system displays the default cursor.

Default Action

The DefWindowProc function returns the handle of the default cursor.

Remarks

When the user drags the icon of a window without a class icon, Windows replaces the icon with a default cursor. If the application requires a different cursor to be displayed during dragging, it must return the handle of the cursor or icon compatible with the display driver's resolution. If an application returns the handle of a color cursor or icon, the system converts the cursor or icon to black and white. The application can call the LoadCursor or LoadIcon function to load a cursor or icon from the resources in its executable (.EXE) file and to retrieve this handle.

See Also

DefWindowProc, LoadCursor, LoadIcon


WM_QUERYENDSESSION

Windows 95:

WM_QUERYENDSESSION

nSource = (UINT) wParam;    // source of end-session request

fLogOff = (BOOL) lParam    // logoff flag

Windows NT:

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.

Parameters

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 Shut Down Windows dialog box. This parameter is nonzero if the user clicked the End Task button in the Task List dialog box.

fLogOff

Windows 95 only: Value of lParam. Indicates whether the user is logging off or shutting down the system. This parameter is TRUE if the user is logging off; it is FALSE if the user is shutting down the system.

Return Value

If an application can terminate conveniently, it should return TRUE; otherwise, it should return FALSE.

Default Action

The DefWindowProc function returns TRUE.

Remarks

Note that lParam is not used on the Windows NT platform, but is used on the Windows 95 platform.

See Also

DefWindowProc, ExitWindows, WM_ENDSESSION


WM_QUERYNEWPALETTE

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.

Return Value

If the window realizes its logical palette, it must return TRUE; otherwise, it must return FALSE.

See Also

WM_PALETTECHANGED, WM_PALETTEISCHANGING


WM_QUERYOPEN

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.

Return Value

If the icon can be opened, an application that processes this message should return TRUE; otherwise, it should return FALSE to prevent the icon from being opened.

Default Action

The DefWindowProc function returns TRUE.

Remarks

While processing this message, the application should not perform any action that would cause an activation or focus change (for example, creating a dialog box).

See Also

DefWindowProc


WM_QUEUESYNC

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.

Return Value

A CBT application should return zero if it processes this message.

Remarks

Whenever a CBT application uses the WH_JOURNALPLAYBACK hook procedure, the first and last messages are WM_QUEUESYNC. This allows the CBT application to intercept and examine user-initiated messages without doing so for events that it sends.

If an application specifies a NULL window handle, the message is posted to the message queue of the active window.


WM_QUIT

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.

Parameters

nExitCode

Value of wParam. Specifies the exit code given in the PostQuitMessage function.

Return Value

This message does not have a return value, because it causes the message loop to terminate before the message is sent to the application's window procedure.

See Also

GetMessage, PostQuitMessage


WM_RASDIALEVENT

WM_RASDIALEVENT

rasconnstate = (RASCONNSTATE) wParam; // connection state about to be entered

dwError = (DWORD) lParam;             // error that may have occurred

The operating system sends a WM_RASDIALEVENT message to a window procedure when a change of state event occurs during a Remote Access Service (RAS) connection process, and a window has been specified to handle notifications of such events by using the notifier parameter of RasDial.

The two message parameters are equivalent to the parameters of the same names that are used with RasDialFunc and RasDialFunc1 callback functions.

Parameters

rasconnstate

Value of wParam. Equivalent to the rasconnstate parameter of the RasDialFunc and RasDialFunc1 callback functions. Specifies a RASCONNSTATE enumerator value that indicates the state the RasDial remote access connection process is about to enter.

dwError

Value of lParam. Equivalent to the dwError parameter of the RasDialFunc and RasDialFunc1 callback functions. A nonzero value indicates the error that has occurred, or zero if no error has occurred.

RasDial sends this message with dwError set to zero upon entry to each connection state. If an error occurs within a state, the message is sent again for the state, this time with a nonzero dwError value.

Return Value

If an application processes this message, it should return TRUE.

See Also

RasDial, RasDialFunc, RasDialFunc1, RASCONNSTATE


WM_RBUTTONDBLCLK

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.

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

Return Value

If an application processes this message, it should return zero.

Remarks

Only windows that have the CS_DBLCLKS style can receive WM_RBUTTONDBLCLK messages, which Windows generates whenever the user presses, releases, and again presses the right mouse button within the system's double-click time limit. Double-clicking the right mouse button actually generates four messages: WM_RBUTTONDOWN, WM_RBUTTONUP, WM_RBUTTONDBLCLK, and WM_RBUTTONUP again.

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, GetDoubleClickTime, MAKEPOINTS, POINTS, SetCapture, SetDoubleClickTime, WM_RBUTTONDOWN, WM_RBUTTONUP


WM_RBUTTONDOWN

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.

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_RBUTTON	Set if the right mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

Return Value

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_RBUTTONDBLCLK, WM_RBUTTONUP


WM_RBUTTONUP

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.

Parameters

fwKeys

Value of wParam. Indicates whether various virtual keys are down. This parameter can be any combination of the following values:

Value	Description
MK_CONTROL	Set if the CTRL key is down.
MK_LBUTTON	Set if the left mouse button is down.
MK_MBUTTON	Set if the middle mouse button is down.
MK_SHIFT	Set if the SHIFT key is down.
xPos

Value of the low-order word of lParam. Specifies the x-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

yPos

Value of the high-order word of lParam. Specifies the y-coordinate of the cursor. The coordinate is relative to the upper left corner of the client area.

Return Value

If an application processes this message, it should return zero.

Remarks

An application can use the MAKEPOINTS macro to convert the lParam parameter to a POINTS structure.

See Also

GetCapture, MAKEPOINTS, POINTS, SetCapture, WM_RBUTTONDBLCLK, WM_RBUTTONDOWN


WM_RENDERALLFORMATS

WM_RENDERALLFORMATS

The WM_RENDERALLFORMATS message is sent to the clipboard owner before it is destroyed, if the clipboard owner has delayed rendering one or more clipboard formats. For the content of the clipboard to remain available to other applications, the clipboard owner must render data in all the formats it is capable of generating, and place the data on the clipboard by calling the SetClipboardData function.

Parameters

This message has no parameters.

Return Value

If an application processes this message, it should return zero.

Remarks

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 SetClipboardData.

See Also

SetClipboardData, WM_RENDERFORMAT


WM_RENDERFORMAT

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.

Parameters

uFormat

Specifies the clipboard format to be rendered.

Return Value

If an application processes this message, it should return zero.

Remarks

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

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.

Parameters

hwnd

Value of wParam. Identifies the window that contains the cursor.

nHittest

Value of the low-order word of lParam. Specifies the hit-test code.

wMouseMsg

Value of the high-order word of lParam. Specifies the identifier of the mouse message.

Default Action

The DefWindowProc function passes the WM_SETCURSOR message to a parent window before processing. If the parent window returns TRUE, further processing is halted. Passing the message to a window's parent window gives the parent window control over the cursor's setting in a child window. The DefWindowProc function also uses this message to set the cursor to an arrow if it is not in the client area, or to the registered class cursor if it is in the client area. If the low-order word of the lParam parameter is HTERROR and the high-order word of lParam specifies that one of the mouse buttons is pressed, DefWindowProc calls the MessageBeep function.

Remarks

The high-order word of lParam is zero when the window enters menu mode.

See Also

DefWindowProc, MessageBeep


WM_SETFOCUS

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.

Parameters

hwndLoseFocus

Value of wParam. Identifies the window that has lost the keyboard focus (may be NULL).

Return Value

An application should return zero if it processes this message.

Remarks

To display a caret, an application should call the appropriate caret functions when it receives the WM_SETFOCUS message.

See Also

SetFocus, WM_KILLFOCUS


WM_SETFONT

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.

Parameters

hfont

Value of wParam. Identifies the font. If this parameter is NULL, the control uses the default system font to draw text.

fRedraw

Value of lParam. Specifies whether the control should be redrawn immediately upon setting the font. Setting the fRedraw parameter to TRUE causes the control to redraw itself.

Return Value

This message does not return a value.

Remarks

The WM_SETFONT message applies to all controls, not just those in dialog boxes.

The best time for the owner of a dialog box control to set the font of the control is when it receives the WM_INITDIALOG message. The application should call the DeleteObject function to delete the font when it is no longer needed; for example, after it destroys the control.

The size of the control does not change as a result of receiving this message. To avoid clipping text that does not fit within the boundaries of the control, the application should correct the size of the control window before it sets the font.

When a dialog box uses the DS_SETFONT style to set the text in its controls, Windows sends the WM_SETFONT message to the dialog box procedure before it creates the controls. An application can create a dialog box that contains the DS_SETFONT style by calling any of the following functions:

•	CreateDialogIndirect

•	CreateDialogIndirectParam

•	DialogBoxIndirect

•	DialogBoxIndirectParam

See Also

CreateDialogIndirect, CreateDialogIndirectParam, DeleteObject, DialogBoxIndirect, DialogBoxIndirectParam, WM_INITDIALOG, DLGTEMPLATE


WM_SETHOTKEY

WM_SETHOTKEY

wParam = (WPARAM) MAKEWORD(vkey, modifiers)   // virtual-key code and modifiers 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.

Parameters

vkey

Value of wParam. Specifies the virtual-key code and modifiers of the hot key to associate with the window. The virtual-key code is in the low byte of the parameter and the modifier flags are in the high byte. Setting this parameter to NULL removes the hot key associated with a window. The modifier byte can be a combination of the following flags:

Value	Meaning
HOTKEYF_ALT	ALT key
HOTKEYF_CONTROL	CTRL key
HOTKEYF_EXT	Extended key
HOTKEYF_SHIFT	SHIFT key
Return Value

The return value is one of the following:

Value	Meaning
−1	The function is unsuccessful — the hot key is invalid.
..0	The function is unsuccessful — the window is invalid.
..1	The function is successful, and no other window has the same hot key.
..2	The function is successful, but another window already has the same hot key.
Remarks

A hot key cannot be associated with a child window.

VK_ESCAPE, VK_SPACE, and VK_TAB are invalid hot keys.

When the user presses the hot key, the system generates a WM_SYSCOMMAND message with wParam equal to SC_HOTKEY.

A window can only have one hot key. If the window already has a hot key associated with it, the new hot key replaces the old one. If more than one window has the same hot key, the window that is activated by the hot key is random.

These hot keys are unrelated to the hot keys set by RegisterHotKey.

See Also

RegisterHotKey, WM_GETHOTKEY, WM_SYSCOMMAND


WM_SETICON  (preliminaryWindows 95)
WM_SETICON  [image]  (preliminary−Windows 95)

WM_SETICON

wParam = (WPARAM) (BOOL) fType;    // icon size (large or small)

lParam = (LPARAM) (HICON) hicon;   // handle of icon

An application sends the WM_SETICON message to associate a new big or small icon with a window. Windows draws the big icon when the window is minimized, and the small icon in the window's title bar.

Parameters

fType

Value of wParam. Specifies the icon being set. If TRUE, the message sets the big icon. If FALSE, the message sets the small icon.

hicon

Value of lParam. Identifies the new big or small icon. If this parameter is NULL, the icon indicated by fType is removed.

Return Value

The return value is the handle of the previous big or small icon, depending on the value of fType. It is NULL if the window previously had no icon of the type indicated by fType.

Default Action

The DefWindowProc function returns the handle of the previous big or small icon associated with the window, depending on the value of fType.

See Also

DefWindowProc, WM_GETICON


WM_SETREDRAW

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.

Parameters

fRedraw

Value of wParam. Specifies the state of the redraw flag. If this parameter is TRUE, the redraw flag is set. If the parameter is FALSE, the flag is cleared.

Return Value

An application should return zero if it processes this message.

Remarks

This message sets or clears the redraw flag. If the redraw flag is cleared, the content of the given window is not updated after each change, and the window is not repainted until the redraw flag is set. For example, an application that must add several items to a list box can clear the redraw flag, add the items, and then set the redraw flag. Finally, the application can call the InvalidateRect function to cause the list box to be repainted.

See Also

InvalidateRect


WM_SETTEXT

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.

Parameters

lpsz

Value of lParam. Points to a null-terminated string that is the window text.

Return Value

The return value is TRUE if the text is set. It is FALSE (for an edit control), LB_ERRSPACE (for a list box), or CB_ERRSPACE (for a combo box) if insufficient space is available to set the text in the edit control. It is CB_ERR if this message is sent to a combo box without an edit control.

Default Action

The DefWindowProc function sets and displays the window text.

Remarks

For an edit control, the text is the contents of the edit control. For a combo box, the text is the contents of the edit-control portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title.

This message does not change the current selection in the list box of a combo box. An application should use the CB_SELECTSTRING message to select the item in a list box that matches the text in the edit control.

See Also

DefWindowProc, CB_SELECTSTRING, WM_GETTEXT


WM_SETTINGCHANGE  (preliminaryWindows 95)
WM_SETTINGCHANGE  (preliminary−Windows 95)

WM_SETTINGCHANGE

wParam = wFlag;                         // system-wide parameter flag

lParam = (LPARAM) (LPCTSTR) pszMetrics; // metrics name

The WM_SETTINGCHANGE message is sent to all windows when an application changes a systemwide setting by using the SystemParametersInfo function.

Parameters

wFlag

Value of wParam. Specifies the systemwide parameter that has changed. For a list of values, see the SystemParametersInfo function.

pszMetrics

Points to a buffer that contains the string "WindowMetrics" if wFlag specifies any of the following systemwide parameters. This parameter is NULL, otherwise.

SPI_SETANIMATION

SPI_SETNONCLIENTMETRICS

SPI_SETICONMETRICS

SPI_SETMINIMIZEDMETRICS

Return Value

An application should return zero if it processes this message.

Remarks

Windows NT: The WM_SETTINGCHANGE message is implemented on the Windows 95 platform. It is not implemented on the Windows NT platform. The Windows NT message WM_WININICHANGE provides equivalent functionality.

See Also

SystemParametersInfo, WM_WININICHANGE


WM_SHOWWINDOW

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.

Parameters

fShow

Value of wParam. Specifies whether a window is being shown. It is TRUE if the window is being shown or FALSE if the window is being hidden.

fnStatus

Value of lParam. Specifies the status of the window being shown. The fnStatus parameter is zero if the message is sent because of a call to the ShowWindow function; otherwise, fnStatus is one of the following values:

Value	Meaning
SW_OTHERUNZOOM	Window is being uncovered because a maximize window was restored or minimized.
SW_OTHERZOOM	Window is being covered by another window that has been maximized.
SW_PARENTCLOSING	Window's owner window is being minimized.
SW_PARENTOPENING	Window's owner window is being restored.
Return Value

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function hides or shows the window, as specified by the message.

Remarks

If a window has the WS_VISIBLE style when it is created, the window receives this message after it is created, but before it is displayed. A window also receives this message when its visibility state is changed by the ShowWindow or ShowOwnedPopups function.

The WM_SHOWWINDOW message is not sent under the following circumstances:

•	When a top-level, overlapped window is created with the WS_MAXIMIZE or WS_MINIMIZE style.

•	When the SW_SHOWNORMAL flag is specified in the call to the ShowWindow function.

See Also

DefWindowProc, ShowOwnedPopups, ShowWindow


WM_SIZE

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.

Parameters

fwSizeType

Value of wParam. Specifies the type of resizing requested. This parameter can be one of the following values:

Value	Meaning
SIZE_MAXHIDE	Message is sent to all pop-up windows when some other window is maximized.
SIZE_MAXIMIZED	Window has been maximized.
SIZE_MAXSHOW	Message is sent to all pop-up windows when some other window has been restored to its former size.
SIZE_MINIMIZED	Window has been minimized.
SIZE_RESTORED	Window has been resized, but neither the SIZE_MINIMIZED nor SIZE_MAXIMIZED value applies.
nWidth

Value of the low-order word of lParam. Specifies the new width of the client area.

nHeight

Value of the high-order word of lParam. Specifies the new height of the client area.

Return Value

If an application processes this message, it should return zero.

Remarks

If the SetScrollPos or MoveWindow function is called for a child window as a result of the WM_SIZE message, the bRedraw parameter should be nonzero to cause the window to be repainted.

Although the width and height of a window are 32-bit values, the nWidth and nHeight parameters of the WM_SIZE message contain only the low-order 16 bits.

See Also

MoveWindow, SetScrollPos


WM_SIZECLIPBOARD

WM_SIZECLIPBOARD

hwndViewer = (HWND) wParam;  // handle of clipboard viewer window

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.

Parameters

hwndViewer

Value of wParam. Identifies the clipboard viewer window.

hglbRc

Value of lParam. Identifies a global memory object that contains a RECT structure. The structure specifies the new dimensions of the clipboard viewer's client area.

Remarks

When the clipboard viewer window is about to be destroyed or resized, a WM_SIZECLIPBOARD message is sent with a null rectangle (0, 0, 0, 0) as the new size. This permits the clipboard owner to free its display resources.

The clipboard owner must use the GlobalLock function to lock the memory object that contains RECT. Before returning, the clipboard owner must unlock the object by using the GlobalUnlock function.

See Also

GlobalLock, GlobalUnlock, RECT


WM_SIZING  (preliminaryWindows 95)
WM_SIZING  [image]  (preliminary−Windows 95)

fwSide = wParam;         // edge of window being sized

lprc = (LPRECT) lParam;  // screen coordinates of drag rectangle

The WM_SIZING message is sent to a window that the user is resizing. By processing this message, an application can monitor the size and position of the drag rectangle and, if needed, change its size or position.

Parameters

fwSide

Value of wParam. Indicates which edge of the window is being sized. This parameter can be a combination of the following values:

Value	Meaning
WMSZ_BOTTOM	Bottom edge
WMSZ_BOTTOMLEFT	Bottom-left corner
WMSZ_BOTTOMRIGHT	Bottom-right corner
WMSZ_LEFT	Left edge
WMSZ_RIGHT	Right edge
WMSZ_TOP	Top edge
WMSZ_TOPLEFT	Top-left corner
WMSZ_TOPRIGHT	Top-right corner
lprc

Address of a RECT structure with the screen coordinates of the drag rectangle. To change the size or position of the drag rectangle, an application must change the members of this structure.

Return Value

An application should return TRUE if it processes this message.

See Also

WM_MOVING, WM_SIZE


WM_SPOOLERSTATUS

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.

Parameters

fwJobStatus

Value of wParam. Specifies the PR_JOBSTATUS flag.

cJobsLeft

Value of the low-order word of lParam. Specifies the number of jobs remaining in the Print Manager queue.

Return Value

An application should return zero if it processes this message.

Remarks

This message is for informational purposes only.


WM_STYLECHANGED  (preliminaryWindows NT)
WM_STYLECHANGED  [image]  (preliminary−Windows NT)

WM_STYLECHANGED

wStyleType = wParam;            // extended or nonextended styles

lpss = (LPSTYLESTRUCT) lParam;  // structure containing new styles

The WM_STYLECHANGED message is sent to a window after the SetWindowLong function has changed one or more of the window's styles.

Parameters

wStyleType

Value of wParam. Specifies whether the window's extended or nonextended styles have changed. This parameter can be a combination of the following values:

Value	Meaning
GWL_EXSTYLE	The window's extended styles have changed.
GWL_STYLE	The window's nonextended styles have changed.
lpss

Value of lParam. Points to a STYLESTRUCT structure that contains the new styles for the window. An application can examine the styles, but can not change them.

Return Value

An application should return zero if it processes this message.

See Also

SetWindowLong, STYLESTRUCT, WM_STYLECHANGING


WM_STYLECHANGING  (preliminaryWindows NT)
WM_STYLECHANGING  [image]  (preliminary−Windows NT)

WM_STYLECHANGING

wStyleType = wParam;            // extended or nonextended styles

lpss = (LPSTYLESTRUCT) lParam;  // structure containing new styles

The WM_STYLECHANGING message is sent to a window when the SetWindowLong function is about to change one or more of the window's styles.

Parameters

wStyleType

Value of wParam. Specifies whether the window's extended or nonextended styles have changed. This parameter can be a combination of the following values:

Value	Meaning
GWL_EXSTYLE	The window's extended styles are changing.
GWL_STYLE	The window's nonextended styles are changing.
lpss

Value of lParam. Points to a STYLESTRUCT structure that contains the proposed new styles for the window. An application can examine the styles and, if necessary, change them.

Return Value

An application should return zero if it processes this message.

See Also

STYLESTRUCT, WM_STYLECHANGED


WM_SYSCHAR

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.

Parameters

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 the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.
Return Value

An application should return zero if it processes this message.

Remarks

When the context code is zero, the message can be passed to the TranslateAccelerator function, which will handle it as though it were a standard key message instead of a system character-key message. This allows accelerator keys to be used with the active window even if the active window does not have the keyboard focus.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; the PRINT SCRN key; the BREAK key; the NUMLOCK key; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateAccelerator, TranslateMessage, WM_SYSKEYDOWN


WM_SYSCOLORCHANGE

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.

Remarks

Windows sends a WM_PAINT message to any window that is affected by a system color change.

Applications that have brushes using the existing system colors should delete those brushes and recreate them using the new system colors.

See Also

WM_PAINT


WM_SYSCOMMAND

WM_SYSCOMMAND

uCmdType = wParam;        // type of system command requested

xPos = LOWORD(lParam);    // horizontal postion, in screen coordinates

yPos = HIWORD(lParam);    // vertical postion, in screen coordinates

A window receives this message 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.

Parameters

uCmdType

Specifies the type of system command requested. This can be one of these values:

Value	Meaning
SC_CLOSE	Closes the window.
SC_CONTEXTHELP	Changes the cursor to a question mark with a pointer. If the user then clicks a control in the dialog box, the control receives a WM_HELP message.
SC_DEFAULT	Selects the default item; the user double-clicked the System menu.
SC_HOTKEY	Activates the window associated with the application-specified hot key. The low-order word of lParam identifies the window to activate.
SC_HSCROLL	Scrolls horizontally.
SC_KEYMENU	Retrieves the System menu as a result of a keystroke.
SC_MAXIMIZE (or SC_ZOOM)	Maximizes the window.
SC_MINIMIZE (or SC_ICON)	Minimizes the window.
SC_MONITORPOWER	Windows 95 only: Sets the state of the display. This command supports devices that have power-saving features, such as a battery-powered personal computer.
SC_MOUSEMENU	Retrieves the System menu as a result of a mouse click.
SC_MOVE	Moves the window.
SC_NEXTWINDOW	Moves to the next window.
SC_PREVWINDOW	Moves to the previous window.
SC_RESTORE	Restores the window to its normal position and size.
SC_SCREENSAVE	Executes the screen saver application specified in the [boot] section of the SYSTEM.INI file.
SC_SIZE	Sizes the window.
SC_TASKLIST	Executes or activates Windows Task Manager.
SC_VSCROLL	Scrolls vertically.
xPos

Specifies the horizontal position of the cursor, in screen coordinates, if a System menu command is chosen with the mouse. Otherwise, the xPos parameter is not used.

yPos

Specifies the vertical position of the cursor, in screen coordinates, if a System menu command is chosen with the mouse. This parameter is − 1 if the command is chosen using a system accelerator, or zero if using a mnenomic.

Return Value

An application should return zero if it processes this message.

Remarks

The DefWindowProc function carries out the System menu request for the predefined actions specified in the previous table.

In WM_SYSCOMMAND messages, the four low-order bits of the uCmdType parameter are used internally by Windows. To obtain the correct result when testing the value of uCmdType, an application must combine the value 0xFFF0 with the uCmdType value by using the bitwise AND operator.

The menu items in a System menu can be modified by using the GetSystemMenu, AppendMenu, InsertMenu, ModifyMenu, InsertMenuItem, and SetMenuItem 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 DefWindowProc. Any WM_SYSCOMMAND messages not handled by the application must be passed to DefWindowProc. Any command values added by an application must be processed by the application and cannot be passed to DefWindowProc.

Accelerator keys that are defined to choose items from the 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

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.

Parameters

chCharCode

Value of wParam. Specifies the character code generated by the system dead key — that is, a dead key that is pressed while holding down the ALT key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.
Return Value

An application should return zero if it processes this message.

Remarks

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateMessage, WM_DEADCHAR, WM_SYSKEYDOWN


WM_SYSKEYDOWN

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.

Parameters

nVirtKey

Value of wParam. Specifies the virtual-key code of the key being pressed.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is down while the key is pressed; it is 0 if the WM_SYSKEYDOWN message is posted to the active window because no window has the keyboard focus.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is always 0 for a WM_SYSKEYDOWN message.
Return Value

An application should return zero if it processes this message.

Default Action

The DefWindowProc function examines the given key and generates a WM_SYSCOMMAND message if the key is either TAB or ENTER.

Remarks

When the context code is zero, the message can be passed to the TranslateAccelerator function, which will handle it as though it were a normal key message instead of a system character-key message. This allows accelerator keys to be used with the active window even if the active window does not have the keyboard focus.

Because of automatic repeat, more than one WM_SYSKEYDOWN message may occur before a WM_SYSKEYUP message is sent. The previous key state (bit 30) can be used to determine whether the WM_SYSKEYDOWN message indicates the first down transition or a repeated down transition.

For enhanced 101- and 102-key keyboards, enhanced keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lParam parameter.

See Also

DefWindowProc, TranslateAccelerator, WM_SYSCOMMAND, WM_SYSKEYUP


WM_SYSKEYUP

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.

Parameters

nVirtKey

Value of wParam. Specifies the virtual-key code of the key being released.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key. The repeat count is always one for a WM_SYSKEYUP message.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is down while the key is released; it is 0 if the WM_SYSKEYDOWN message is posted to the active window because no window has the keyboard focus.
30	Specifies the previous key state. The value is always 1 for a WM_SYSKEYUP message.
31	Specifies the transition state. The value is always 1 for a WM_SYSKEYUP message.
Return Value

An application should return zero if it processes this message.

Default Action

The DefWindowProc function sends a WM_SYSCOMMAND message to the top-level window if the F10 key or the ALT key was released. The wParam parameter of the message is set to SC_KEYMENU.

Remarks

When the context code is zero, the message can be passed to the TranslateAccelerator function, which will handle it as though it were a normal key message instead of a system character-key message. This allows accelerator keys to be used with the active window even if the active window does not have the keyboard focus.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Other keyboards may support the extended-key bit in the lKeyData parameter.

For non-U.S. enhanced 102-key keyboards, the right ALT key is handled as a CTRL+ALT key. The following table shows the sequence of messages that result when the user presses and releases this key:

Message	Virtual-key code
WM_KEYDOWN	VK_CONTROL
WM_KEYDOWN	VK_MENU
WM_KEYUP	VK_CONTROL
WM_SYSKEYUP	VK_MENU
See Also

DefWindowProc, TranslateAccelerator, WM_SYSCOMMAND, WM_SYSKEYDOWN


WM_TCARD  (preliminaryWindows 95)
WM_TCARD  (preliminary−Windows 95)

WM_TCARD

idAction = wParam;

dwActionData = lParam;

The WM_TCARD message is sent to an application that has initiated a training card with Windows Help. The message informs the application when the user clicks an authorable button. An application initiates a training card by specifying the HELP_TCARD command in a call to the WinHelp function.

Parameters

idAction

Value of wParam. Indicates the action the user has taken. This parameter can be one of these values:

Value	Meaning
IDABORT	The user clicked an authorable Abort button.
IDCANCEL	The user clicked an authorable Cancel button.
IDCLOSE	The user closed the training card.
IDHELP	The user clicked an authorable Windows Help button.
IDIGNORE	The user clicked an authorable Ignore button.
IDOK	The user clicked an authorable OK button.
IDNO	The user clicked an authorable No button.
IDRETRY	The user clicked an authorable Retry button.
HELP_TCARD_DATA	The user clicked an authorable button. The lParam parameter contains a long integer specified by the help author.
HELP_TCARD_NEXT	The user clicked an authorable Next button.
HELP_TCARD_OTHER_CALLER	Another application has requested training cards.
IDYES	The user clicked an authorable Yes button.
dwActionData

Value of lParam. If idAction specifies HELP_TCARD_DATA, this parameter is a long integer specified by the help author. Otherwise, this parameter is zero.

Return Value

The return value is ignored; use zero.

See Also

WinHelp


WM_TIMECHANGE

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.

Return Value

An application should return zero if it processes this message.

Remarks

An application that changes the system time should send this message to all top-level windows. To send the WM_TIMECHANGE message to all top-level windows, an application can use the SendMessage function with the hwnd parameter set to HWND_TOPMOST.

See Also

SendMessage


WM_TIMER

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.

Parameters

wTimerID

Value of wParam. Specifies the timer identifier.

tmprc

Value of lParam. Points to an application-defined callback function that was passed to the SetTimer function when the timer was installed. If the tmprc parameter is not NULL, Windows passes the WM_TIMER message to the specified callback function rather than posting the message to the thread's message queue.

Return Value

An application should return zero if it processes this message.

Remarks

The DispatchMessage function forwards this message when no other messages are in the thread's message queue.

See Also

DispatchMessage, SetTimer, TimerProc


WM_UNDO

WM_UNDO

wParam = 0; // not used; must be zero

lParam = 0; // not used; must be zero

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.

Return Value

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

WM_USER

The WM_USER constant is used by applications to help define private messages.

Remarks

The WM_USER constant is used to distinguish between message values that are reserved for use by Windows and values that can be used by an application to send messages within a private window class. There are five ranges of message numbers:

Range	Meaning
0 through WM_USER − 1	Messages reserved for use by Windows.
WM_USER through 0x7FFF	Integer messages for use by private window classes.
0x8000 through 0xBFFF	Messages reserved for future use by Windows.
0xC000 through 0xFFFF	String messages for use by applications.
Greater than 0xFFFF	Reserved by Windows for future use.
Message numbers in the first range (0 through WM_USER − 1) are defined by Windows. Values in this range that are not explicitly defined are reserved for future use by Windows.

Message numbers in the second range (WM_USER through 0x7FFF) can be defined and used by an application to send messages within a private window class. These values cannot be used to define messages that are meaningful throughout an application, because some predefined window classes already define values in this range. For example, predefined control classes such as BUTTON, EDIT, LISTBOX, and COMBOBOX may use these values. Messages in this range should not be sent to other applications unless the applications have been designed to exchange messages and to attach the same meaning to the message numbers.

Message numbers in the third range (0x8000 through 0xBFFF) are reserved for future use by Windows.

Message numbers in the fourth range (0xC000 through 0xFFFF) are defined at run time when an application calls the RegisterWindowMessage function to retrieve a message number for a string. All applications that register the same string can use the associated message number for exchanging messages. The actual message number, however, is not a constant and cannot be assumed to be the same between different Windows sessions.

Message numbers in the fifth range (greater than 0xFFFF) are reserved for future use by Windows.

See Also

RegisterWindowMessage


WM_USERCHANGED  (preliminaryWindows 95)
WM_USERCHANGED  (preliminary−Windows 95)

WM_USERCHANGED

wParam = 0;       // not used, must be zero

lParam = 0;       // not used, must be zero

The WM_USERCHANGED message is sent to all windows after the user has logged on or off. When the user logs on or off, the system updates the user-specific settings. The system sends this message immediately after updating the settings.

Return Value

An application should return zero if it processes this message.


WM_VKEYTOITEM

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.

Parameters

vkey

Value of the low-order word of wParam. Specifies the virtual-key code of the key the user pressed.

nCaretPos

Value of the high-order word of wParam. Specifies the current position of the caret.

hwndLB

Value of lParam. Identifies the list box.

Return Value

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

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.

Parameters

nScrollCode

Value of the low-order word of wParam. Specifies a scroll bar value that indicates the user's scrolling request. This parameter can be one of the following values:

Value	Meaning
SB_BOTTOM	Scrolls to the lower right.
SB_ENDSCROLL	Ends scroll.
SB_LINEDOWN	Scrolls one line down.
SB_LINEUP	Scrolls one line up.
SB_PAGEDOWN	Scrolls one page down.
SB_PAGEUP	Scrolls one page up.
SB_THUMBPOSITION	Scrolls to the absolute position. The current position is specified by the nPos parameter.
SB_THUMBTRACK	Drags scroll box to the specified position. The current position is specified by the nPos parameter.
SB_TOP	Scrolls to the upper left.
nPos

Value of the high-order word of wParam. Specifies the current position of the scroll box if the nScrollCode parameter is SB_THUMBPOSITION or SB_THUMBTRACK; otherwise, nPos is not used.

hwndScrollBar

Value of lParam. Identifies the control if WM_VSCROLL is sent by a scroll bar control. If WM_VSCROLL is sent by a window's standard scroll bar, hwndScrollBar is not used.

Return Value

If an application processes this message, it should return zero.

Remarks

The SB_THUMBTRACK notification message is typically used by applications that provide feedback as the user drags the scroll box.

If an application scrolls the content of the window, it must also reset the position of the scroll box by using the SetScrollPos function.

Note that the WM_VSCROLL message carries only 16 bits of scroll box position data. Thus, applications that rely solely on WM_VSCROLL (and WM_HSCROLL) for scroll position data have a practical maximum position value of 65,535.

However, because the SetScrollPos, SetScrollRange, GetScrollPos, and GetScrollRange functions support 32-bit scroll bar position data, there is a way to circumvent the 16-bit barrier of the WM_HSCROLL and WM_VSCROLL messages. See GetScrollPos for a description of the technique and its limits.

See Also

GetScrollPos, GetScrollRange, SetScrollPos, SetScrollRange, WM_HSCROLL


WM_VSCROLLCLIPBOARD

WM_VSCROLLCLIPBOARD

hwndViewer = (HWND) wParam;         // handle of clipboard viewer window

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.

Parameters

hwndViewer

Value of wParam. Identifies the clipboard viewer window.

nScrollCode

Value of the low-order word of lParam. Specifies a scroll bar event. This parameter can be one of the following values:

Value	Meaning
SB_BOTTOM	Scroll to lower right.
SB_ENDSCROLL	End scroll.
SB_LINEDOWN	Scroll one line down.
SB_LINEUP	Scroll one line up.
SB_PAGEDOWN	Scroll one page down.
SB_PAGEUP	Scroll one page up.
SB_THUMBPOSITION	Scroll to absolute position. The current position is specified by the nPos parameter.
SB_TOP	Scroll to upper left.
nPos

Value of the high-order word of lParam. Specifies the current position of the scroll box if the nScrollCode parameter is SB_THUMBPOSITION; otherwise, the nPos parameter is not used.

Return Value

If an application processes this message, it should return zero.

Remarks

The clipboard owner can use the ScrollWindow function to scroll the image in the clipboard viewer window and invalidate the appropriate region.

See Also

ScrollWindow


WM_WINDOWPOSCHANGED

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 the SetWindowPos function or another window-management function.

Parameters

lpwp

Value of lParam. Points to a WINDOWPOS structure that contains information about the window's new size and position.

Return Value

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function sends the WM_SIZE and WM_MOVE messages to the window.

Remarks

The WM_SIZE and WM_MOVE messages are not sent if an application handles the WM_WINDOWPOSCHANGED message without calling DefWindowProc. It is more efficient to perform any move or size change processing during the WM_WINDOWPOSCHANGED message without calling DefWindowProc.

See Also

DefWindowProc, EndDeferWindowPos, SetWindowPos, WINDOWPOS, WM_MOVE, WM_SIZE, WM_WINDOWPOSCHANGING


WM_WINDOWPOSCHANGING

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 the SetWindowPos function or another window-management function.

Parameters

lpwp

Value of lParam. Points to a WINDOWPOS structure that contains information about the window's new size and position.

Return Value

If an application processes this message, it should return zero.

Default Action

For a window with the WS_OVERLAPPED or WS_THICKFRAME style, the DefWindowProc function sends the WM_GETMINMAXINFO message to the window. This is done to validate the new size and position of the window and to enforce the CS_BYTEALIGNCLIENT and CS_BYTEALIGNWINDOW client styles. By not passing the WM_WINDOWPOSCHANGING message to the DefWindowProc function, an application can override these defaults.

Remarks

While this message is being processed, modifying any of the values in WINDOWPOS affects the window's new size, position, or place in the Z order. An application can prevent changes to the window by setting or clearing the appropriate bits in the flags member of WINDOWPOS.

See Also

DefWindowProc, EndDeferWindowPos, SetWindowPos, WINDOWPOS, WM_GETMINMAXINFO, WM_MOVE, WM_SIZE, WM_WINDOWPOSCHANGED


WM_WININICHANGE

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.

Parameters

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.

Return Value

An application should return zero if it processes this message.

Remarks

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.

Windows 95: The WM_WININICHANGE message is implemented on the Windows NT platform. It is not implemented on the Windows 95 platform. The Windows 95 message WM_SETTINGCHANGE provides equivalent functionality.

See Also

SendMessage, SystemParametersInfo, WM_DEVMODECHANGE WM_SETTINGCHANGE


LB_SETCOLUMNWIDTH

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.

Parameters

cxColumn

Value of wParam. Specifies the width, in pixels, of all columns.

Return Value

This message does not return a value.

See Also

LB_SETTABSTOPS


LB_SETCOUNT

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 and not created with the LBS_HASSTRINGS style.

Parameters

cItems

Value of wParam. Specifies the new count of items in the list box.

Return Value

If an error occurs, the return value is LB_ERR. If there is insufficient memory to store the items, the return value is LB_ERRSPACE.

Remarks

The LB_SETCOUNT message is supported only by list boxes created with the LBS_NODATA style and not created with the LBS_HASSTRINGS style. All other list boxes return LB_ERR.

See Also

LB_GETCOUNT


LB_SETCURSEL

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the string that is selected. If the index parameter is -1, the list box is set to have no selection.

Return Value

If an error occurs, the return value is LB_ERR. If the index parameter is −1, the return value is LB_ERR even though no error occurred.

Remarks

Use this message only with single-selection list boxes. You cannot use it to set or remove a selection in a multiple-selection list box.

See Also

LB_GETCURSEL


LB_SETHORIZONTALEXTENT

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.

Parameters

cxExtent

Value of wParam. Specifies the number of pixels by which the list box can be scrolled.

Return Value

This message does not return a value.

Remarks

To respond to the LB_SETHORIZONTALEXTENT message, the list box must have been defined with the WS_HSCROLL style.

See Also

LB_GETHORIZONTALEXTENT


LB_SETITEMDATA

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.

Parameters

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.

Return Value

If an error occurs, the return value is LB_ERR.

Remarks

If the item is in an owner-drawn list box created without the LBS_HASSTRINGS style, this message replaces the 32-bit value contained in the lParam parameter of the LB_ADDSTRING or LB_INSERTSTRING message that added the item to the list box.

See Also

LB_ADDSTRING, LB_GETITEMDATA, LB_INSERTSTRING


LB_SETITEMHEIGHT

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the item in the list box. Use this parameter only if the list box has the LBS_OWNERDRAWVARIABLE style; otherwise, set it to zero.

cyItem

Value of lParam. Specifies the height, in pixels, of the item.

Return Value

If the index or height is invalid, the return value is LB_ERR.

See Also

LB_GETITEMHEIGHT


LB_SETLOCALE

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.

Parameters

wLocaleID

Value of wParam. Specifies the locale identifier that the list box will use for sorting when adding text.

Return Value

The return value is the previous locale identifier. If the wLocaleID parameter specifies a locale that is not installed on the system, the return value is LB_ERR and the current list box locale is not changed.

Remarks

Use the MAKELCID macro to construct a locale identifier.

See Also

LB_ADDSTRING, LB_GETLOCALE, MAKELCID


LB_SETSEL

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.

Parameters

fSelect

Value of wParam. Specifies how to set the selection. If the fSelect parameter is TRUE, the string is selected and highlighted; if fSelect is FALSE, the highlight is removed and the string is no longer selected.

index

Value of lParam. Specifies the zero-based index of the string to set. If index is −1, the selection is added to or removed from all strings, depending on the value of fSelect.

Return Value

If an error occurs, the return value is LB_ERR.

Remarks

Use this message only with multiple-selection list boxes.

See Also

LB_GETSEL, LB_SELITEMRANGE


LB_SETTABSTOPS

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.

Parameters

cTabs

Value of wParam. Specifies the number of tab stops in the list box.

lpnTabs

Value of lParam. Points to the first member of an array of integers containing the tab stops, in dialog box units. The tab stops must be sorted in ascending order; backward tabs are not allowed.

Return Value

If all the specified tabs are set, the return value is TRUE; otherwise, it is FALSE.

Remarks

To respond to the LB_SETTABSTOPS message, the list box must have been created with the LBS_USETABSTOPS style.

If cTabs parameter is 0 and lpnTabs is NULL, the default tab stop is two dialog box units. If cTabs is 1, the list box will have tab stops separated by the distance specified by lpnTabs.

If lpnTabs points to more than a single value, a tab stop will be set for each value in lpnTabs, up to the number specified by cTabs.

A dialog box unit is a horizontal or vertical distance. One horizontal dialog box unit is equal to 0.25 of the current dialog box base-width unit. These units are computed based on the height and width of the current system font. The GetDialogBaseUnits function returns the current dialog box base units, in pixels.

See Also

GetDialogBaseUnits


LB_SETTOPINDEX

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.

Parameters

index

Value of wParam. Specifies the zero-based index of the item in the list box.

Return Value

If an error occurs, the return value is LB_ERR.

Remarks

The system scrolls the list box contents so that either the specified item appears at the top of the list box or the maximum scroll range has been reached.

See Also

LB_GETTOPINDEX


LBN_DBLCLK

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.

Remarks

Only a list box that has the LBS_NOTIFY style will send this notification message.

See Also

LBN_SELCHANGE, WM_COMMAND


LBN_ERRSPACE

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

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

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.

Remarks

This notification message applies only to list boxes of the LBS_NOTIFY style.

See Also

LB_SETCURSEL, LBN_DBLCLK, LBN_SELCHANGE, WM_COMMAND


LBN_SELCHANGE

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.

Remarks

This notification message is not sent if the LB_SETCURSEL message changes the selection.

This notification message applies only to a list box that has the LBS_NOTIFY style.

For a multiple-selection list box, the LBN_SELCHANGE notification is sent whenever the user presses an arrow key, even if the selection does not change.

See Also

LB_SETCURSEL, LBN_DBLCLK, LBN_SELCANCEL, WM_COMMAND


LBN_SETFOCUS

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


LVM_ARRANGE  (preliminaryWindows NT)
LVM_ARRANGE  (preliminary−Windows NT)

LVM_ARRANGE

wParam = (WPARAM) (int) code;

lParam = 0;

// Corresponding macro

BOOL ListView_Arrange(HWND hwnd, UINT code);

The LVM_ARRANGE message arranges items in icon view. You can send this message explicitly or by using the ListView_Arrange macro.

Parameters

hwnd

Handle to the list view control.

code

Alignment that can be combined with an optional sort flag. The alignment can be one of the following values:

Value	Meaning
LVA_ALIGNBOTTOM	Aligns items along the bottom edge of the window.
LVA_ALIGNLEFT	Aligns items along the left edge of the window.
LVA_ALIGNRIGHT	Aligns items along the right edge of the window.
LVA_ALIGNTOP	Aligns items along the top edge of the window.
LVA_DEFAULT	Aligns items according to the list view control's current alignment styles (the default value).
LVA_SNAPTOGRID	Snaps all icons to the nearest grid position.
The sort flag, if specified, sorts items by text in ascending or descending order; it can be the LVA_SORTASCENDING or LVA_SORTDESCENDING value.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVM_CREATEDRAGIMAGE  (preliminaryWindows NT)
LVM_CREATEDRAGIMAGE  (preliminary−Windows NT)

LVM_CREATEDRAGIMAGE

wParam = (WPARAM) (int) iItem;

lParam = (LPARAM) (LPPOINT) lpptUpLeft;

// Corresponding macro

HIMAGELIST ListView_CreateDragImage(HWND hwnd, int iItem,

LPPOINT lpptUpLeft);

The LVM_CREATEDRAGIMAGE message creates a drag image list for the specified item. You can send this message explicitly or by using the ListView_CreateDragImage macro.

Parameters

hwnd

Handle to the list view control.

iItem

Index of the item.

lpptUpLeft

Pointer to a POINT structure that receives the initial location of the upper-left corner of the image, in view coordinates.

Return Value

Returns the handle to the drag image list if successful or NULL otherwise.

See Also

POINT


LVM_DELETEALLITEMS  (preliminaryWindows NT)
LVM_DELETEALLITEMS  (preliminary−Windows NT)

LVM_DELETEALLITEMS

wParam = 0;

lParam = 0;

// Corresponding macro

BOOL ListView_DeleteAllItems(HWND hwnd);

The LVM_DELETEALLITEMS message removes all items from a list view control. You can send this message explicitly or by using the ListView_DeleteAllItems macro.

Parameters

hwnd

Handle to the list view control.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVM_DELETECOLUMN  (preliminaryWindows NT)
LVM_DELETECOLUMN  (preliminary−Windows NT)

LVM_DELETECOLUMN

wParam = (WPARAM) (int) iCol;

lParam = 0;

// Corresponding macro

BOOL ListView_DeleteColumn(HWND hwnd, int iCol);

The LVM_DELETECOLUMN message removes a column from a list view control. You can send this message explicitly or by using the ListView_DeleteColumn macro.

Parameters

hwnd

Handle to the list view control.

iCol

Index of the column to delete.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVM_DELETEITEM  (preliminaryWindows NT)
LVM_DELETEITEM  (preliminary−Windows NT)

LVM_DELETEITEM

wParam = (WPARAM) (int) iItem;

lParam = 0;

// Corresponding macro

BOOL ListView_DeleteItem(HWND hwnd, int iItem);

The LVM_DELETEITEM message removes an item from a list view control. You can send this message explicitly or by using the ListView_DeleteItem macro.

Parameters

hwnd

Handle to the list view control.

iItem

Index of the list view item to delete.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVM_EDITLABEL  (preliminaryWindows NT)
LVM_EDITLABEL  (preliminary−Windows NT)

LVM_EDITLABEL

wParam = (WPARAM) (int) iItem;

lParam = 0;

// Corresponding macro

HWND ListView_EditLabel(HWND hwnd, int iItem);

The LVM_EDITLABEL message begins in-place editing of the specified list view item's text. The message implicitly selects and focuses the specified item. You can send this message explicitly or by using the ListView_EditLabel macro.

Parameters

hwnd

Handle to the list view control.

iItem

Index of the list view item. To cancel editing, set iItem to −1.

Return Value

Returns the handle of the edit control that is used to edit the item text if successful or NULL otherwise.

Remarks

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See Also

WM_CANCELMODE, SetFocus


LVM_ENSUREVISIBLE  (preliminaryWindows NT)
LVM_ENSUREVISIBLE  (preliminary−Windows NT)

LVM_ENSUREVISIBLE

wParam = (WPARAM) (int) iItem;

lParam = (LPARAM) (BOOL) fPartialOk;

// Corresponding macro

BOOL ListView_EnsureVisible(HWND hwnd, int i, BOOL fPartialOK);

The LVM_ENSUREVISIBLE message ensures that a list view item is entirely or at least partially visible, scrolling the list view control if necessary. You can send this message explicitly or by using the ListView_EnsureVisible macro.

Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

fPartialOK

Value specifying whether the item must be entirely visible. If this parameter is TRUE, no scrolling occurs if the item is at least partially visible.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVM_FINDITEM  (preliminaryWindows NT)
LVM_FINDITEM  (preliminary−Windows NT)

LVM_FINDITEM

wParam = (WPARAM) (int) iStart;

lParam = (LPARAM) (const LV_FINDINFO FAR *) plvfi;

// Corresponding macro

int ListView_FindItem(HWND hwnd, int iStart,

    const LV_FINDINFO FAR* plvfi);

The LVM_FINDITEM message searches for a list view item with the specified characteristics. You can send this message explicitly or by using the ListView_FindItem macro.

Parameters

hwnd

Handle to the list view control.

iStart

Index of the item to begin the search with or −1 to start from the beginning. The specified item is itself excluded from the search.

plvfi

Pointer to an LV_FINDINFO structure that contains information about what to search for.

Return Value

Returns the index of the item if successful or −1 otherwise.

See Also

LV_FINDINFO


LVM_GETBKCOLOR  (preliminaryWindows NT)
LVM_GETBKCOLOR  (preliminary−Windows NT)

LVM_GETBKCOLOR

wParam = 0;

lParam = 0;

// Corresponding macro

COLORREF ListView_GetBkColor(HWND hwnd);

The LVM_GETBKCOLOR message retrieves the background color of a list view control. You can send this message explicitly or by using the ListView_GetBkColor macro.

Parameters

hwnd

Handle to the list view control.

Return Value

Returns the background color of the list view control.


LVM_GETCALLBACKMASK  (preliminaryWindows NT)
LVM_GETCALLBACKMASK  (preliminary−Windows NT)

LVM_GETCALLBACKMASK

wParam = 0;

lParam = 0;

// Corresponding macro

UINT ListView_GetCallbackMask(HWND hwnd);

The LVM_GETCALLBACKMASK message retrieves the callback mask for a list view control. You can send this message explicitly or by using the ListView_GetCallbackMask macro.

Parameters

hwnd

Handle to the list view control.

Return Value

Returns the callback mask.


LVM_GETCOLUMN  (preliminaryWindows NT)
LVM_GETCOLUMN  (preliminary−Windows NT)

LVM_GETCOLUMN

wParam = (WPARAM) (int) iCol;

lParam = (LPARAM) (LV_COLUMN FAR *) pcol;

// Corresponding macro

BOOL ListView_GetColumn(HWND hwnd, int iCol,

LV_COLUMN FAR* pcol);

The LVM_GETCOLUMN message retrieves the attributes of a list view control's column. You can send this message explicitly or by using the ListView_GetColumn macro.

Parameters

hwnd

Handle to the list view control.

iCol

Index of the column.

pcol

Pointer to an LV_COLUMN structure that specifies the information to retrieve and receives information about the column. The mask member specifies which column attributes to retrieve.

If the mask member specifies the LVCF_TEXT value, the pszText member must contain the pointer to the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

LV_COLUMN


LVM_GETCOLUMNWIDTH  (preliminaryWindows NT)
LVM_GETCOLUMNWIDTH  (preliminary−Windows NT)

LVM_GETCOLUMNWIDTH

wParam = (WPARAM) (int) iCol;

lParam = 0;

// Corresponding macro

int ListView_GetColumnWidth(HWND hwnd, int iCol);

The LVM_GETCOLUMNWIDTH message retrieves the width of a column in report or list view. You can send this message explicitly or by using the ListView_GetColumnWidth macro.

Parameters

hwnd

Handle to the list view control.

iCol

Index of the column. This parameter is ignored in list view.

Return Value

Returns the column width if successful or zero otherwise.


LVM_GETCOUNTPERPAGE  (preliminaryWindows NT)
LVM_GETCOUNTPERPAGE  (preliminary−Windows NT)

LVM_GETCOUNTPERPAGE

wParam = 0;

lParam = 0;

// Corresponding macro

int ListView_GetCountPerPage(HWND hwnd);

The LVM_GETCOUNTPERPAGE message calculates the number of items that can fit vertically in the visible area of a list view control when in list or report view. Only fully-visible items are counted. You can send this message explicitly, or by using the ListView_GetCountPerPage macro.

Parameters

hwnd

Handle to the list view control.

Return Value

Returns the number of fully-visible items if successful. If the current view is icon or small icon view, the return value is the total number of items in the list view control.


LVM_GETEDITCONTROL  (preliminaryWindows NT)
LVM_GETEDITCONTROL  (preliminary−Windows NT)

LVM_GETEDITCONTROL

wParam = 0;

lParam = 0;

// Corresponding macro

HWND ListView_GetEditControl(HWND hwnd);

The LVM_GETEDITCONTROL message retrieves the handle to the edit control being used to edit a list view item's text. You can send this message explicitly or by using the ListView_GetEditControl macro.

Parameters

hwnd

Handle to the list view control.

Return Value

Returns the handle to the edit control if successful or NULL otherwise.

Remarks

If no label is being edited, the return value is NULL. The edit control is not created until after the LVN_BEGINLABELEDIT notification message is sent.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it. To cancel editing, you can send the list view control a WM_CANCELMODE message.

The list view item being edited is the currently focused item — that is, the item in the focused state. To find an item based on its state, use the LVM_GETNEXTITEM message.

See Also

LVN_BEGINLABELEDIT, LVM_GETNEXTITEM, WM_CANCELMODE


LVM_GETIMAGELIST  (preliminaryWindows NT)
LVM_GETIMAGELIST  (preliminary−Windows NT)

LVM_GETIMAGELIST

wParam = (WPARAM) (int) iImageList;

lParam = 0;

// Corresponding macro

HIMAGELIST ListView_GetImageList(HWND hwnd, int iImageList);

The LVM_GETIMAGELIST message retrieves the handle to an image list used for drawing list view items. You can send this message explicitly or by using the ListView_GetImageList macro.

Parameters

hwnd

Handle to the list view control.

iImageList

Image list to retrieve. This parameter can be one of the following values:

Value	Meaning
LVSIL_NORMAL	Image list with large icons
LVSIL_SMALL	Image list with small icons
LVSIL_STATE	Image list with state images
Return Value

Returns the handle of the specified image list if successful or NULL otherwise.


LVM_GETISEARCHSTRING

LVM_GETISEARCHSTRING

wParam = 0;

lParam = (LPARAM) (LPSTR) lpsz;

// Corresponding macro

BOOL ListView_GetISearchString(HWND hwnd, LPSTR lpsz);

The LVM_GETISEARCHSTRING message retrieves the incremental search string of a list view control. You can send this message explicitly or by using the ListView_GetISearchString macro.

Parameters

hwnd

Handle of the list view control.

lpsz

Address of a buffer that receives the incremental search string.

Return Value

Returns the number of characters in the incremental search string, or zero if the list view control is not in incremental search mode.

Remarks

The incremental search string is the character sequence that the user enters while the list view has the input focus. Each time the user enters a character, the system appends the character to the search string and then searches for a matching item. If the system finds a match, it selects the item and, if necessary, scrolls it into view.

A timeout period is associated with each character that the user enters. If the timeout period elapses before the user enters another character, the incremental search string is reset.


LVM_GETITEM  (preliminaryWindows NT)
LVM_GETITEM  (preliminary−Windows NT)

LVM_GETITEM

wParam = 0;

lParam = (LPARAM) (LV_ITEM FAR*) pitem;

// Corresponding macro

BOOL ListView_GetItem(HWND hwnd, LV_ITEM FAR* pitem);

The LVM_GETITEM message retrieves some or all of a list view item's attributes. You can send this message explicitly or by using the ListView_GetItem macro.

Parameters

hwnd

Handle to the list view control.

pitem

Pointer to an LV_ITEM structure that specifies the information to retrieve and receives information about the list view item.

When the message is sent, the iItem and iSubItem members identify the item or subitem to retrieve information about and the mask member specifies which attributes to retrieve. For a list of possible values, see the description of the LV_ITEM structure.

If the mask member specifies the LVIF_TEXT value, the pszText member must contain the pointer to the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states are to be returned.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

LV_ITEM


LVM_GETITEMCOUNT  (preliminaryWindows NT)
LVM_GETITEMCOUNT  (preliminary−Windows NT)

LVM_GETITEMCOUNT

wParam = 0;

lParam = 0;

// Corresponding macro

int ListView_GetItemCount(HWND hwnd);

The LVM_GETITEMCOUNT message retrieves the number of items in a list view control. You can send this message explicitly or by using the ListView_GetItemCount macro.

Parameters

hwnd

Handle to the list view control.

Return Value

Returns the number of items.


LVM_GETITEMPOSITION  (preliminaryWindows NT)
LVM_GETITEMPOSITION  (preliminary−Windows NT)

LVM_GETITEMPOSITION

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (POINT FAR *) ppt;

// Corresponding macro

BOOL ListView_GetItemPosition(HWND hwnd, int i, POINT FAR* ppt);

The LVM_GETITEMPOSITION message retrieves the position of a list view item. You can send this message explicitly or by using the ListView_GetItemPosition macro.

Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

ppt

Pointer to a POINT structure that receives the position of the item's upper-left corner, in view coordinates.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

POINT


LVM_GETITEMRECT  (preliminaryWindows NT)
LVM_GETITEMRECT  (preliminary−Windows NT)

LVM_GETITEMRECT

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (LPRECT) prc;

// Corresponding macro

BOOL ListView_GetItemRect(HWND hwnd, int i, RECT FAR* prc, int code);

The LVM_GETITEMRECT message retrieves the bounding rectangle for all or part of an item in the current view. You can send this message explicitly or by using the ListView_GetItemRect macro.

Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

prc

Pointer to a RECT structure that receives the bounding rectangle. When the message is sent, the left member of this structure contains the value of the code parameter.

code

Portion of the list view item for which to retrieve the bounding rectangle. This parameter can be one of the following values:

Value	Meaning
LVIR_BOUNDS	Returns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICON	Returns the bounding rectangle of the icon or small icon.
LVIR_LABEL	Returns the bounding rectangle of the item text.
LVIR_SELECTBOUNDS	Returns a rectangle in which the user must click to select the list view item.
Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

This parameter is specified by the left member of the RECT structure pointed to by prc.

See Also

RECT


LVM_GETITEMSPACING  (preliminaryWindows NT)
LVM_GETITEMSPACING  (preliminary−Windows NT)

LVM_GETITEMSPACING

wParam = (WPARAM) (BOOL) fSmall;

lParam = 0;

// Corresponding macro

DWORD ListView_GetItemSpacing(HWND hwnd, BOOL fSmall);

The LVM_GETITEMSPACING message determines the spacing between items in a list view control. You can send this message explicitly or by using the ListView_GetItemSpacing macro.

Parameters

hwnd

Handle to the list view control.

fSmall

View to retrieve the item spacing for. This parameter is TRUE for small icon view, or FALSE for icon view.

Return Value

Returns the amount of spacing between items.


LVM_GETITEMSTATE  (preliminaryWindows NT)
LVM_GETITEMSTATE  (preliminary−Windows NT)

LVM_GETITEMSTATE

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (UINT) mask;

// Corresponding macro

UINT WINAPI ListView_GetItemState(HWND hwnd, int i, UINT mask);

The LVM_GETITEMSTATE message retrieves the state of a list view item. You can send this message explicitly or by using the ListView_GetItemState macro.

Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

mask

Mask that specifies which of the item's state flags to return.

Return Value

Returns the item's state flags.


LVM_GETITEMTEXT  (preliminaryWindows NT)
LVM_GETITEMTEXT  (preliminary−Windows NT)

LVM_GETITEMTEXT

wParam = (WPARAM) (int) iItem;

lParam = (LPARAM) (LV_ITEM FAR *) pitem;

// Corresponding macro

void WINAPI ListView_GetItemText(HWND hwnd, int iItem,

     int iSubItem, LPSTR pszText, int cchTextMax);

The LVM_GETITEMTEXT message retrieves the text of a list view item or subitem.

Parameters

The message has the following parameters:

hwnd

Handle to the list view control.

iItem

Index of the list view item.

pitem

Pointer to an LV_ITEM structure. The iSubItem member specifies the index of a subitem, or it can be zero to get the item label. The pszText member points to a buffer that receives the text, and the cchTextMax member specifies the size of the buffer.

The macro has the following parameters:

hwnd

Handle to the list view control.

iItem

Index of the list view item.

iSubItem

Index of the subitem, or zero to retrieve the item label.

pszText

Pointer to the buffer that receives the item or subitem text.

cchTextMax

Size of the buffer, in bytes.

Return Value

If you send this message explicitly, it returns the length of the retrieved string.

If you can send this message implicitly by using the ListView_GetItemText macro, there is no return value.

See Also

LV_ITEM


LVM_GETNEXTITEM  (preliminaryWindows NT)
LVM_GETNEXTITEM  (preliminary−Windows NT)

LVM_GETNEXTITEM

wParam = (WPARAM) (int) iStart;

lParam = MAKELPARAM((UINT) flags, 0);

// Corresponding macro

int ListView_GetNextItem(HWND hwnd, int iStart, UINT flags);

The LVM_GETNEXTITEM message searches for a list view item that has the specified properties and bears the specified relationship to a specified item. You can send this message explicitly or by using the ListView_GetNextItem macro.

Parameters

hwnd

Handle to the list view control.

iStart

Index of the item to begin the searching with, or −1 to find the first item that matches the specified flags. The specified item itself is excluded from the search.

flags

Geometric relation of the requested item to the specified item and, if specified, the state of the requested item.

The geometric relation can be one of the following values:

Value	Meaning
LVNI_ABOVE	Searches for an item that is above the specified item.
LVNI_ALL	Searches for a subsequent item by index (the default value).
LVNI_BELOW	Searches for an item that is below the specified item.
LVNI_TOLEFT	Searches for an item to the left of the specified item.
LVNI_TORIGHT	Searches for an item to the right of the specified item.
The state can be zero, or it can be one or more of the following values:

Value	Meaning
LVNI_CUT	The item has the LVIS_CUT state flag set.
LVNI_DROPHILITED	The item has the LVIS_DROPHILITED state flag set.
LVNI_FOCUSED	The item has the LVIS_FOCUSED state flag set.
LVNI_SELECTED	The item has the LVIS_SELECTED state flag set.
If an item does not have all of the specified state flags set, the search continues with the next item.

Return Value

Returns the index of the next item if successful or −1 otherwise.


LVM_GETORIGIN  (preliminaryWindows NT)
LVM_GETORIGIN  (preliminary−Windows NT)

LVM_GETORIGIN

wParam = 0;

lParam = (LPARAM) (LPPOINT) lpptOrg;

// Corresponding macro

BOOL ListView_GetOrigin(HWND hwnd, LPPOINT lpptOrg);

The LVM_GETORIGIN message retrieves the current view origin for a list view control. You can send this message explicitly or by using the ListView_GetOrigin macro.

Parameters

hwnd

Handle to the list view control.

lpptOrg

Pointer to a POINT structure that receives the view origin.

Return Value

Returns TRUE if successful or FALSE if the current view is list or report view.

See Also

POINT


LVM_GETSELECTEDCOUNT  (preliminaryWindows NT)
LVM_GETSELECTEDCOUNT  (preliminary−Windows NT)

LVM_GETSELECTEDCOUNT

wParam = 0;

lParam = 0;

// Corresponding macro

UINT ListView_GetSelectedCount(HWND hwnd);

The LVM_GETSELECTEDCOUNT message determines the number of selected items in a list view control. You can send this message explicitly or by using the ListView_GetSelectedCount macro.

Parameters

hwnd

Handle to the list view control.

Return Value

Returns the number of selected items.


LVM_GETSTRINGWIDTH  (preliminaryWindows NT)
LVM_GETSTRINGWIDTH  (preliminary−Windows NT)

LVM_GETSTRINGWIDTH

wParam = 0;

lParam = (LPARAM) (LPCSTR) psz;

// Corresponding macro

int ListView_GetStringWidth(HWND hwnd, LPCSTR psz);

The LVM_GETSTRINGWIDTH message determines the width of a specified string, using the specified list view control's current font. You can send this message explicitly or by using the ListView_GetStringWidth macro.

Parameters

hwnd

Handle to the list view control.

psz

Pointer to a null-terminated string.

Return Value

Returns the string width if successful or zero otherwise.

Remarks

The return value specifies the string width in the control's current font. An application can use this value to set column widths in report view. When setting the width of the first column (column zero), an application should add to the return value the width of the small icon and state image, if any.


LVM_GETTEXTBKCOLOR  (preliminaryWindows NT)
LVM_GETTEXTBKCOLOR  (preliminary−Windows NT)

LVM_GETTEXTBKCOLOR

wParam = 0;

lParam = 0;

// Corresponding macro

COLORREF ListView_GetTextBkColor(HWND hwnd);

The LVM_GETTEXTBKCOLOR message retrieves the text background color of a list view control. You can send this message explicitly or by using the ListView_GetTextBkColor macro.

Parameters

hwnd

Handle to the list view control.

Return Value

Returns the background color of the text.


LVM_GETTEXTCOLOR  (preliminaryWindows NT)
LVM_GETTEXTCOLOR  (preliminary−Windows NT)

LVM_GETTEXTCOLOR

wParam = 0;

lParam = 0;

// Corresponding macro

COLORREF ListView_GetTextColor(HWND hwnd);

The LVM_GETTEXTCOLOR message retrieves the text color of a list view control. You can send this message explicitly or by using the ListView_GetTextColor macro.

Parameters

hwnd

Handle to the list view control.

Return Value

Returns the text color.


LVM_GETTOPINDEX  (preliminaryWindows NT)
LVM_GETTOPINDEX  (preliminary−Windows NT)

LVM_GETTOPINDEX

wParam = 0;

lParam = 0;

// Corresponding macro

int ListView_GetTopIndex(HWND hwnd);

The LVM_GETTOPINDEX message retrieves the index of the topmost visible item when in list or report view. You can send this message explicitly or by using the ListView_GetTopIndex macro.

Parameters

hwnd

Handle to the list view control.

Return Value

Returns the index of the item if successful or zero if the list view control is in icon or small icon view.


LVM_GETVIEWRECT  (preliminaryWindows NT)
LVM_GETVIEWRECT  (preliminary−Windows NT)

LVM_GETVIEWRECT

wParam = 0;

lParam = (LPARAM) (RECT FAR *) prc;

// Corresponding macro

BOOL ListView_GetViewRect(HWND hwnd, RECT FAR* prc);

The LVM_GETVIEWRECT message retrieves the bounding rectangle of all items in the list view control. The list view must be in icon or small icon view. You can send this message explicitly or by using the ListView_GetViewRect macro.

Parameters

hwnd

Handle to the list view control.

prc

Pointer to a RECT structure that receives the bounding rectangle. All coordinates are relative to the visible area of the list view control.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

RECT


LVM_HITTEST  (preliminaryWindows NT)
LVM_HITTEST  (preliminary−Windows NT)

LVM_HITTEST

wParam = 0;

lParam = (LPARAM) (LV_HITTESTINFO FAR *) pinfo;

// Corresponding macro

int ListView_HitTest(HWND hwnd, LV_HITTESTINFO FAR* pinfo);

The LVM_HITTEST message determines which list view item, if any, is at a specified position. You can send this message explicitly or by using the ListView_HitTest macro.

Parameters

hwnd

Handle to the list view control.

pinfo

Pointer to an LV_HITTESTINFO structure that contains the position to hit test and receives information about the results of the hit test.

Return Value

Returns the index of the item at the specified position, if any, or −1 otherwise.

See Also

LV_HITTESTINFO


LVM_INSERTCOLUMN  (preliminaryWindows NT)
LVM_INSERTCOLUMN  (preliminary−Windows NT)

LVM_INSERTCOLUMN

wParam = (WPARAM) (int) iCol;

lParam = (LPARAM) (const LV_COLUMN FAR *) pcol;

// Corresponding macro

int ListView_InsertColumn(HWND hwnd, int iCol,

    const LV_COLUMN FAR* pcol);

The LVM_INSERTCOLUMN message inserts a new column in a list view control. You can send this message explicitly or by using the ListView_InsertColumn macro.

Parameters

hwnd

Handle to the list view control.

iCol

Index of the new column.

pcol

Pointer to an LV_COLUMN structure that contains the attributes of the new column.

Return Value

Returns the index of the new column if successful or −1 otherwise.

See Also

LV_COLUMN


LVM_INSERTITEM  (preliminaryWindows NT)
LVM_INSERTITEM  (preliminary−Windows NT)

LVM_INSERTITEM

wParam = 0;

lParam = (LPARAM) (const LV_ITEM FAR *) pitem;

// Corresponding macro

int ListView_InsertItem(HWND hwnd, const LV_ITEM FAR* pitem);

The LVM_INSERTITEM message inserts a new item in a list view control. You can send this message explicitly or by using the ListView_InsertItem macro.

Parameters

hwnd

Handle to the list view control.

pitem

Pointer to an LV_ITEM structure that specifies the attributes of the list view item. The iItem member specifies the index of the new item. The iSubItem member must be zero; the macro cannot be used to insert subitems.

Return Value

Returns the index of the new item if successful or −1 otherwise.

See Also

LV_ITEM


LVM_REDRAWITEMS  (preliminaryWindows NT)
LVM_REDRAWITEMS  (preliminary−Windows NT)

LVM_REDRAWITEMS

wParam = (int) iFirst;  // index of first item to redraw

lParam = (int), iLast;  // index of last item to redraw

// Corresponding macro

BOOL ListView_RedrawItems(HWND hwnd, int iFirst, int iLast);

The LVM_REDRAWITEMS message forces a list view control to redraw a range of items. You can send this message explicitly or by using the ListView_RedrawItems macro.

Parameters

hwnd

Handle to the list view control.

iFirst

Index of the first item to redraw.

iLast

Index of the last item to redraw.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

The specified items are not actually redrawn until the list view window receives a WM_PAINT message to repaint. To repaint immediately, call the UpdateWindow function after using this macro.

See Also

UpdateWindow, WM_PAINT


LVM_SCROLL  (preliminaryWindows NT)
LVM_SCROLL  (preliminary−Windows NT)

LVM_SCROLL

wParam = (int) dx;  // amount of horizontal scrolling, in pixels

lParam = (int) dy;   // amount of vertical scrolling, in pixels

// Corresponding macro

BOOL ListView_Scroll(HWND hwnd, int dx, int dy);

The LVM_SCROLL message scrolls the content of a list view control. You can send this message explicitly or by using the ListView_Scroll macro.

Parameters

hwnd

Handle to the list view control.

dx and dy

Amount of horizontal and vertical scrolling, in pixels. If the current view is report view, dx must be zero and dy is the number of lines to scroll.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVM_SETBKCOLOR  (preliminaryWindows NT)
LVM_SETBKCOLOR  (preliminary−Windows NT)

LVM_SETBKCOLOR

wParam = 0;

lParam = (LPARAM) (COLORREF) clrBk;

// Corresponding macro

BOOL ListView_SetBkColor(HWND hwnd, COLORREF clrBk);

The LVM_SETBKCOLOR message sets the background color of a list view control. You can send this message explicitly or by using the ListView_SetBkColor macro.

Parameters

hwnd

Handle to the list view control.

clrBk

Background color to set or the CLR_NONE value for no background color. List view controls with background colors redraw themselves significantly faster than those without background colors.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVM_SETCALLBACKMASK  (preliminaryWindows NT)
LVM_SETCALLBACKMASK  (preliminary−Windows NT)

LVM_SETCALLBACKMASK

wParam = (WPARAM) (UINT) mask;

lParam = 0;

// Corresponding macro

BOOL ListView_SetCallbackMask(HWND hwnd, UINT mask);

The LVM_SETCALLBACKMASK message sets the callback mask for a list view control. You can send this message explicitly or by using the ListView_SetCallbackMask macro.

Parameters

hwnd

Handle to the list view control.

mask

New value of the callback mask.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVM_SETCOLUMN  (preliminaryWindows NT)
LVM_SETCOLUMN  (preliminary−Windows NT)

LVM_SETCOLUMN

wParam = (WPARAM) (int) iCol;

lParam = (LPARAM) (const LV_COLUMN FAR *) pcol;

// Corresponding macro

BOOL ListView_SetColumn(HWND hwnd, int iCol, LV_COLUMN FAR* pcol);

The LVM_SETCOLUMN message sets the attributes of a list view column. You can send this message explicitly or by using the ListView_SetColumn macro.

Parameters

hwnd

Handle to the list view control.

iCol

Index of the column.

pcol

Pointer to an LV_COLUMN structure that contains the new column attributes. The mask member specifies which column attributes to set.

If the mask member specifies the LVCF_TEXT value, the pszText member is the pointer to a null-terminated string and the cchTextMax member is ignored.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

LV_COLUMN


LVM_SETCOLUMNWIDTH  (preliminaryWindows NT)
LVM_SETCOLUMNWIDTH  (preliminary−Windows NT)

LVM_SETCOLUMNWIDTH

wParam = (WPARAM) (int) iCol;

lParam = MAKELPARAM((int) cx, 0);

// Corresponding macro

BOOL ListView_SetColumnWidth(HWND hwnd, int iCol, int cx);

The LVM_SETCOLUMNWIDTH message changes the width of a column in report or list view. You can send this message explicitly or by using the ListView_SetColumnWidth macro.

Parameters

hwnd

Handle to the list view control.

iCol

Index of the column. In list view, the iCol parameter must be −1.

cx

New width of the column, in list view coordinates, or one of the following values:

Value	Meaning
LVSCW_AUTOSIZE	Automatically sizes the column.
LVSCW_AUTOSIZE_USEHEADER	Automatically sizes the column to fit the header text.


LVM_SETIMAGELIST  (preliminaryWindows NT)
LVM_SETIMAGELIST  (preliminary−Windows NT)

LVM_SETIMAGELIST

wParam = (WPARAM) (int) iImageList;

lParam = (LPARAM) (HIMAGELIST) himl;

// Corresponding macro

HIMAGELIST ListView_SetImageList(HWND hwnd, HIMAGELIST himl, int iImageList);

The LVM_SETIMAGELIST message assigns an image list to a list view control. You can send this message explicitly or by using the ListView_SetImageList macro.

Parameters

hwnd

Handle to the list view control.

himl

Handle to the image list to assign.

iImageList

Type of image list. This parameter can be one of the following values:

Value	Meaning
LVSIL_NORMAL	Image list with large icons
LVSIL_SMALL	Image list with small icons
LVSIL_STATE	Image list with state images
Return Value

Returns the handle of the image list previously associated with the control if successful; NULL otherwise.


LVM_SETITEM  (preliminaryWindows NT)
LVM_SETITEM  (preliminary−Windows NT)

LVM_SETITEM

wParam = 0;

lParam = (LPARAM) (const LV_ITEM FAR *) pitem;

// Corresponding macro

BOOL ListView_SetItem(HWND hwnd, const LV_ITEM FAR* pitem);

The LVM_SETITEM message sets some or all of a list view item's attributes. You can send this message explicitly or by using the ListView_SetItem macro.

Parameters

hwnd

Handle to the list view control.

pitem

Pointer to an LV_ITEM structure that contains the new item attributes. The iItem and iSubItem members identify the item or subitem, and the mask member specifies which attributes to set.

If the mask member specifies the LVIF_TEXT value, the pszText member is the pointer to a null-terminated string and the cchTextMax member is ignored.

If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states to change and the state member contains the values for those states.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

LV_ITEM


LVM_SETITEMCOUNT  (preliminaryWindows NT)
LVM_SETITEMCOUNT  (preliminary−Windows NT)

LVM_SETITEMCOUNT

wParam = (WPARAM) (int) cItems;

lParam = 0;

// Corresponding macro

VOID ListView_SetItemCount(HWND hwnd, int cItems);

The LVM_SETITEMCOUNT message prepares a list view control for adding a large number of items. You can send this message explicitly or by using the ListView_SetItemCount macro.

Parameters

hwnd

Handle to the list view control.

cItems

Number of items that the list view control will ultimately contain.

Return Value

No return value.

Remarks

By sending the LVM_SETITEMCOUNT message before adding a large number of items, you enable a list view control to reallocate its internal data structures only once rather than every time you add an item.


LVM_SETITEMPOSITION  (preliminaryWindows NT)
LVM_SETITEMPOSITION  (preliminary−Windows NT)

LVM_SETITEMPOSITION

wParam = (LPARAM) (int) i;

lParam = MAKELPARAM((int) x, (int) y);

// Corresponding macro

BOOL ListView_SetItemPosition(HWND hwnd, int i, int x, int y);

The LVM_SETITEMPOSITION message moves an item to a specified position in a list view control, which must be in icon or small icon view. You can send this message explicitly or by using the ListView_SetItemPosition macro.

Parameters

hwnd

Handle to the list view control.

i

Index of the list view item.

x and y

New position of the item's upper-left corner, in view coordinates.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

If the list view control has the LVS_AUTOARRANGE style, the list view control is arranged after the position of the item is set.


LVM_SETITEMPOSITION32  (preliminaryWindows NT)
LVM_SETITEMPOSITION32  (preliminary−Windows NT)

LVM_SETITEMPOSITION32

wParam = (WPARAM) (int) iItem;

lParam = (LPARAM) (LPPOINT) lpptNewPos;

// Corresponding macro

void ListView_SetItemPosition32(HWND hwnd, int iItem, int x, int y);

The LVM_SETITEMPOSITION32 message moves an item to a specified position in a list view control, which must be in icon or small icon view. This message differs from the LVM_SETITEMPOSITION message in that it uses 32-bit coordinates.

Parameters

The message has the following parameters:

iItem

Index of the list view item to set the position of.

lpptNewPos

Pointer to a POINT structure that contains the new position of the item, in list view coordinates.

The macro has the following parameters:

hwnd

Handle to the list view control.

iItem

Index of the list view item to set the position of.

x and y

New horizontal and vertical coordinates of the item.

Return Value

No return value.

If you send this message by using the ListView_SetItemPosition32 macro, it has no return value.

See Also

LVM_SETITEMPOSITION, POINT


LVM_SETITEMSTATE  (preliminaryWindows NT)
LVM_SETITEMSTATE  (preliminary−Windows NT)

LVM_SETITEMSTATE

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (LV_ITEM FAR *) pitem;

// Corresponding macro

BOOL WINAPI ListView_SetItemState(HWND hwnd, int i,

     UINT state, UINT mask);

The LVM_SETITEMSTATE message changes the state of an item in a list view control.

Parameters

The message has the following parameters:

i

Index of the list view item.

pitem

Pointer to an LV_ITEM structure. The stateMask member specifies which state bits to change, and the state member contains the new values for those bits. The other members are ignored.

The macro has the following parameters:

hwnd

Handle to the list view control.

i

Index of the list view item.

state

New state bits for the item.

mask

Mask specifying which of the item's current state bits to change.

Return Value

If you send this message explicitly, it returns TRUE if successful or FALSE otherwise.

If you send this message implicitly by using the ListView_SetItemState macro, there is no return value.

See Also

LV_ITEM


LVM_SETITEMTEXT  (preliminaryWindows NT)
LVM_SETITEMTEXT  (preliminary−Windows NT)

LVM_SETITEMTEXT

wParam = (WPARAM) (int) i;

lParam = (LPARAM) (LV_ITEM FAR *) pitem;

// Corresponding macro

VOID WINAPI ListView_SetItemText(HWND hwnd, int i,

int iSubItem, LPCSTR pszText);

The LVM_SETITEMTEXT message changes the text of a list view item or subitem.

Parameters

The message has the following parameters:

i

Index of the list view item.

pitem

Pointer to an LV_ITEM structure. The iSubItem member is the index of the subitem, or it can be zero to set the item label. The pszText member is the pointer to a null-terminated string containing the new text; it can also be NULL.

The macro has the following parameters:

hwnd

Handle to the list view control.

i

Index of the list view item.

iSubItem

Index of the subitem or zero to set the item label.

pszText

Pointer to a null-terminated string that contains the new text. This parameter can be NULL.

Return Value

If you send this message explicitly, it returns TRUE if successful or FALSE otherwise.

If you send this message implicitly by using the ListView_SetItemText macro, there is no return value.

See Also

LV_ITEM


LVM_SETTEXTBKCOLOR  (preliminaryWindows NT)
LVM_SETTEXTBKCOLOR  (preliminary−Windows NT)

LVM_SETTEXTBKCOLOR

wParam = 0;

lParam = (LPARAM) (COLORREF) clrText;

// Corresponding macro

BOOL ListView_SetTextBkColor(HWND hwnd, COLORREF clrText);

The LVM_SETTEXTBKCOLOR message sets the background color of text in a list view control. You can send this message explicitly or by using the ListView_SetTextBkColor macro.

Parameters

hwnd

Handle to the list view control.

clrText

New text color.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVM_SETTEXTCOLOR  (preliminaryWindows NT)
LVM_SETTEXTCOLOR  (preliminary−Windows NT)

LVM_SETTEXTCOLOR

wParam = 0;

lParam = (LPARAM) (COLORREF) clrText;

// Corresponding macro

BOOL ListView_SetTextColor(HWND hwnd, COLORREF clrText);

The LVM_SETTEXTCOLOR message sets the text color of a list view control. You can send this message explicitly or by using the ListView_SetTextColor macro.

Parameters

hwnd

Handle to the list view control.

clrText

New text color.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVM_SORTITEMS  (preliminaryWindows NT)
LVM_SORTITEMS  (preliminary−Windows NT)

LVM_SORTITEMS

wParam = (WPARAM) (LPARAM) lParamSort;

lParam = (LPARAM) (PFNLVCOMPARE) pfnCompare;

// Corresponding macro

BOOL ListView_SortItems(HWND hwnd, PFNLVCOMPARE pfnCompare,

LPARAM lParamSort);

The LVM_SORTITEMS message sorts list view items using an application-defined comparison function. The index of each item changes to reflect the new sequence. You can send this message explicitly or by using the ListView_SortItems macro.

Parameters

hwnd

Handle to the list view control.

pfnCompare

Pointer to the application-defined comparison function. The comparison function is called during the sort operation each time the relative order of two list items needs to be compared. For more information, see the following.

lParamSort

Application-defined value that is passed to the comparison function.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

The comparison function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,

LPARAM lParamSort);

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

The lParam1 and lParam2 parameters specify the item data for the two items being compared. The lParamSort parameter is the same value passed to the LVM_SORTITEMS message.


LVM_UPDATE  (preliminaryWindows NT)
LVM_UPDATE  (preliminary−Windows NT)

LVM_UPDATE

wParam = (WPARAM) iItem;

lParam = 0;

// Corresponding macro

BOOL ListView_Update(HWND hwnd, int iItem);

The LVM_UPDATE message updates a list view item. If the list view control has the LVS_AUTOARRANGE style, this macro causes the list view control to be arranged. You can send this message explicitly or by using the ListView_Update macro.

Parameters

hwnd

Handle to the list view control.

iItem

Index of the item to update.

Return Value

Returns TRUE if successful or FALSE otherwise.


LVN_BEGINDRAG  (preliminaryWindows NT)
LVN_BEGINDRAG  (preliminary−Windows NT)

LVN_BEGINDRAG

pnmv = (NM_LISTVIEW FAR *) lParam;

The LVN_BEGINDRAG notification message notifies a list view control's parent window that a drag-and-drop operation involving the left mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member identifies the item being dragged, and the other members are zero.

Return Value

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_BEGINLABELEDIT  (preliminaryWindows NT)
LVN_BEGINLABELEDIT  (preliminary−Windows NT)

LVN_BEGINLABELEDIT

pdi = (LV_DISPINFO FAR *) lParam;

The LVN_BEGINLABELEDIT notification message notifies a list view control's parent window about the start of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pdi

Pointer to an LV_DISPINFO structure that contains information about the item

Return Value

Returns FALSE to allow label editing or TRUE to prevent it.

See Also

LV_DISPINFO, WM_NOTIFY


LVN_BEGINRDRAG  (preliminaryWindows NT)
LVN_BEGINRDRAG  (preliminary−Windows NT)

LVN_BEGINRDRAG

pnmv = (NM_LISTVIEW FAR *) lParam;

The LVN_BEGINRDRAG notification message notifies a list view control's parent window that a drag-and-drop operation involving the right mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member identifies the item being dragged, and the other members are zero.

Return Value

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_COLUMNCLICK  (preliminaryWindows NT)
LVN_COLUMNCLICK  (preliminary−Windows NT)

LVN_COLUMNCLICK

pnmv = (NM_LISTVIEW FAR *) lParam;

The LVN_COLUMNCLICK notification message notifies a list view control's parent window that a column was clicked. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member is  − 1, and the iSubItem member identifies the column. All other members are zero.

Return Value

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_DELETEALLITEMS  (preliminaryWindows NT)
LVN_DELETEALLITEMS  (preliminary−Windows NT)

LVN_DELETEALLITEMS

pnmv = (NM_LISTVIEW FAR *) lParam;

The LVN_DELETEALLITEMS notification message notifies a list view control's parent window that all items in the control were deleted. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member is  − 1, and the other members are zero.

Return Value

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_DELETEITEM  (preliminaryWindows NT)
LVN_DELETEITEM  (preliminary−Windows NT)

LVN_DELETEITEM

pnmv = (NM_LISTVIEW FAR *) lParam;

The LVN_DELETEITEM notification message notifies a list view control's parent window that an item was deleted. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member identifies the deleted item, and the other members are zero.

Return Value

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_ENDLABELEDIT  (preliminaryWindows NT)
LVN_ENDLABELEDIT  (preliminary−Windows NT)

LVN_ENDLABELEDIT

pdi = (LV_DISPINFO FAR *) lParam;

The LVN_ENDLABELEDIT notification message notifies a list view control's parent window about the end of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pdi

Pointer to an LV_DISPINFO structure. The iItem member identifies the item being edited.

Windows 95: You can determine if editing is being canceled by checking the lpszText member; if it is NULL, the user is canceling editing.

Windows NT: If editing is being canceled, the iItem member of LV_DISPINFO may be -1.

Return Value

No return value.

Remarks

The pszText member of the LV_ITEM structure contained within the LV_DISPINFO structure pointed to by pdi contains a valid value when the LVN_ENDLABELEDIT message is sent, regardless of whether the LVIF_TEXT flag is set in the mask member of the LV_ITEM structure. Note that NULL is a valid value for pszText, indicating the cancellation of the label editing operation.

See Also

LV_DISPINFO, LV_ITEM, WM_NOTIFY,


LVN_GETDISPINFO  (preliminaryWindows NT)
LVN_GETDISPINFO  (preliminary−Windows NT)

LVN_GETDISPINFO

pnmv = (LV_DISPINFO FAR *) lParam;

The LVN_GETDISPINFO notification message is sent to a list view control's parent window. It is a request for the parent window to provide information needed to display or sort a list view item. The LVN_GETDISPINFO notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmv

Pointer to an LV_DISPINFO structure that specifies the type of information required and that receives the information.

Return Value

No return value.

Remarks

If your message handler sets the LVIF_DI_SETITEM flag of the mask member of the LV_ITEM structure contained within the LV_DISPINFO structure pointed to by pnmv, the operating system stores the requested information, and will not ask for it again.

See Also

LV_DISPINFO, WM_NOTIFY


LVN_INSERTITEM  (preliminaryWindows NT)
LVN_INSERTITEM  (preliminary−Windows NT)

LVN_INSERTITEM

pnmv = (NM_LISTVIEW FAR *) lParam;

The LVN_INSERTITEM notification message notifies a list view control's parent window that a new item was inserted. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmv

Pointer to an NM_LISTVIEW structure. The iItem member identifies the new item, and the other members are zero.

Return Value

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_ITEMCHANGED  (preliminaryWindows NT)
LVN_ITEMCHANGED  (preliminary−Windows NT)

LVN_ITEMCHANGED

pnmv = (NM_LISTVIEW FAR *) lParam;

The LVN_ITEMCHANGED notification message notifies a list view control's parent window that an item has changed. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmv

Pointer to an NM_LISTVIEW structure that identifies the item and specifies which of its attributes have changed.

Return Value

No return value.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_ITEMCHANGING  (preliminaryWindows NT)
LVN_ITEMCHANGING  (preliminary−Windows NT)

LVN_ITEMCHANGING

pnmv = (NM_LISTVIEW FAR *) lParam;

The LVN_ITEMCHANGING notification message notifies a list view control's parent window that an item is changing. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmv

Pointer to an NM_LISTVIEW structure that identifies the item and specifies which of its attributes are changing.

Return Value

Returns TRUE to allow the change or FALSE to prevent the change.

See Also

NM_LISTVIEW, WM_NOTIFY


LVN_KEYDOWN  (preliminaryWindows NT)
LVN_KEYDOWN  (preliminary−Windows NT)

LVN_KEYDOWN

pnkd = (LV_KEYDOWN FAR *) lParam;

The LVN_KEYDOWN notification message notifies a list view control's parent window that a key has been pressed. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnkd

Pointer to an LV_KEYDOWN structure.

Return Value

No return value.

See Also

LV_KEYDOWN, WM_NOTIFY


LVN_PEN  (preliminaryWindows NT)
LVN_PEN  [image]  (preliminary−Windows NT)

LVN_PEN

The LVN_PEN notification message notifies a list view control of a pen event.

Remarks

The LVN_PEN notification message is only implemented on the Windows 95 platform. In addition, the computer must have the Microsoft Windows for Pen Computing (Pen Windows) extensions installed. To determine whether Pen Windows is installed on a system, call the GetSystemMetrics function, with nIndex set to SM_PENWINDOWS.

See Also

GetSystemMetrics


LVN_SETDISPINFO  (preliminaryWindows NT)
LVN_SETDISPINFO  (preliminary−Windows NT)

LVN_SETDISPINFO

pnmv = (LV_DISPINFO FAR *) lParam;

The LVN_SETDISPINFO notification message notifies a list view control's parent window that it must update the information it maintains for an item. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmv

Pointer to an LV_DISPINFO structure that specifies information for the changed item.

Return Value

No return value.

Remarks

The pszText member of the LV_ITEM structure contained within the LV_DISPINFO structure pointed to by pnmv contains a valid value when the LVN_SETDISPINFO message is sent, regardless of whether the LVIF_TEXT flag is set in the mask member of the LV_ITEM structure.

See Also

LV_DISPINFO, LV_ITEM, WM_NOTIFY


NM_CLICK  (preliminaryWindows NT)
NM_CLICK  [image]  (preliminary−Windows NT)

NM_CLICK

pnmh = (NMHDR FAR *) lParam;

The NM_CLICK notification message notifies the parent window of a control that the user has clicked the left mouse button within the control. NM_CLICK is sent in the form of a WM_NOTIFY message.


NM_DBLCLK  (preliminaryWindows NT)
NM_DBLCLK  [image]  (preliminary−Windows NT)

NM_DBLCLK

pnmh = (NMHDR FAR *) lParam;

The NM_DBLCLK notification message notifies the parent window of a control that the user has double-clicked the left mouse button within the control. NM_DBLCLK is sent in the form of a WM_NOTIFY message.


NM_KILLFOCUS  (preliminaryWindows NT)
NM_KILLFOCUS  [image]  (preliminary−Windows NT)

NM_KILLFOCUS

pnmh = (NMHDR FAR *) lParam;

The NM_KILLFOCUS notification message notifies the parent window of a control that the control has lost the input focus. NM_KILLFOCUS is sent in the form of a WM_NOTIFY message.


NM_OUTOFMEMORY  (preliminaryWindows NT)
NM_OUTOFMEMORY  [image]  (preliminary−Windows NT)

NM_OUTOFMEMORY

pnmh = (NMHDR FAR *) lParam;

The NM_OUTOFMEMORY notification message notifies the parent window of a control that the control could not complete an operation because there was not enough memory available. NM_OUTOFMEMORY is sent in the form of a WM_NOTIFY message.


NM_RCLICK  (preliminaryWindows NT)
NM_RCLICK  [image]  (preliminary−Windows NT)

NM_RCLICK

pnmh = (NMHDR FAR *) lParam;

The NM_RCLICK notification message notifies the parent window of a control that the user has clicked the right mouse button within the control. NM_RCLICK is sent in the form of a WM_NOTIFY message.


NM_RDBLCLK  (preliminaryWindows NT)
NM_RDBLCLK  [image]  (preliminary−Windows NT)

NM_RDBLCLK

pnmh = (NMHDR FAR *) lParam;

The NM_RDBLCLK notification message notifies the parent window of a control that the user has double-clicked the right mouse button within the control. NM_RDBLCLK is sent in the form of a WM_NOTIFY message.


NM_RETURN  (preliminaryWindows NT)
NM_RETURN  [image]  (preliminary−Windows NT)

NM_RETURN

pnmh = (NMHDR FAR *) lParam;

The NM_RETURN notification message notifies the parent window of a control that the control has the input focus and that the user has pressed the ENTER key. NM_RETURN is sent in the form of a WM_NOTIFY message.


NM_SETFOCUS  (preliminaryWindows NT)
NM_SETFOCUS  [image]  (preliminary−Windows NT)

NM_SETFOCUS

pnmh = (NMHDR FAR *) lParam;

The NM_SETFOCUS notification message notifies the parent window of a control that the control has received the input focus. NM_SETFOCUS is sent in the form of a WM_NOTIFY message.


PB_APMPOWERSTATUSCHANGED  (preliminaryWindows 95)
PB_APMPOWERSTATUSCHANGED  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The PB_APMPOWERSTATUSCHANGED message is sent when a change in the power status of the computer is detected, such as a switch from battery power to A/C or a drop in remaining battery power below a threshold. A window receives this message through the WM_POWERBROADCAST message.

Parameters

dwData

Reserved; must be 0.

Return Value

Returns TRUE.

Remarks

An application should process this message by calling the GetSystemPowerStatus function to retrieve the current power status of the computer. In particular, the application should check the ACLineStatus, BatteryFlag, BatteryLifeTime, and BatteryLifePercent members of the SYSTEM_POWER_STATUS structure for any changes. This message can occur when the battery life time drops to less than 5 minutes, or when the percentage of battery life drops below 10 percent.

See Also

GetSystemPowerStatus, SYSTEM_POWER_STATUS, WM_POWERBROADCAST


PB_APMQUERYSTANDBY  (preliminaryWindows 95)
PB_APMQUERYSTANDBY  (preliminary−Windows 95)

Flags = (DWORD) lParam;

The PB_APMQUERYSTANDBY message is sent to request permission to place the system in standby mode. An installable driver that grants permission should carry out preparations for changing to standby before returning. A driver receives this message through the WM_POWERBROADCAST message.

Parameters

Flags

Action flags. If bit 0 is 1, the installable driver can prompt the user for directions on how to prepare for the change to standby; otherwise, the driver must prepare without user interaction. All other bit values are reserved.

Return Value

Returns TRUE if the change to standby can continue, or FALSE to cancel the change.

Remarks

An installable driver should process this message by first determining whether permission to change to standby can be granted. It must not grant permission if doing so would cause a lost of data. The installable driver can prompt the user for directions on how to prepare for the change to standby only if bit 0 in the Flags parameter is set.

This message is not sent to applications.

See Also

WM_POWERBROADCAST


PB_APMQUERYSTANDBYFAILED  (preliminaryWindows 95)
PB_APMQUERYSTANDBYFAILED  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The PB_APMQUERYSTANDBYFAILED message is sent as a notification that permission to place the computer in standby mode was denied. This message is sent if any installable driver returned FALSE to a previous PB_APMQUERYSTANDBY message. A driver receives this message through the WM_POWERBROADCAST message.

Parameters

dwData

Reserved; must be 0.

Return Value

Returns TRUE.

Remarks

Installable drivers typically respond to this message by resuming normal operation. This message is not sent to applications.

See Also

PB_APMQUERYSTANDBY, WM_POWERBROADCAST


PB_APMQUERYSUSPEND  (preliminaryWindows 95)
PB_APMQUERYSUSPEND  (preliminary−Windows 95)

Flags = (DWORD) lParam;

The PB_APMQUERYSUSPEND message is sent to request permission to suspend the computer. An application that grants permission should carry out preparations for the suspension before returning. A window receives this message through the WM_POWERBROADCAST message.

Parameters

Flags

Action flags. If bit 0 is 1, the application can prompt the user for directions on how to prepare for the suspension; otherwise, the application must prepare without user interaction. All other bit values are reserved.

Return Value

Returns TRUE if the suspension can continue, or FALSE to cancel to suspension.

Remarks

An application should process this message by first determining whether permission to suspend can be granted. It must not grant permission if doing so would cause a loss of data. The application can prompt the user for directions on how to prepare for suspension only if bit 0 in the Flags parameter is set.

See Also

WM_POWERBROADCAST


PB_APMQUERYSUSPENDFAILED  (preliminaryWindows 95)
PB_APMQUERYSUSPENDFAILED  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The PB_APMQUERYSUSPENDFAILED message is sent as a notification that permission to suspend the computer was denied. This message is sent if any application or driver returned FALSE to a previous PB_APMQUERYSUSPEND message. A window receives this message through the WM_POWERBROADCAST message.

Parameters

dwData

Reserved; must be 0.

Return Value

Returns TRUE.

Remarks

Applications typically respond to this message by resuming normal operation.

See Also

PB_APMQUERYSUSPEND, WM_POWERBROADCAST


PB_APMRESUMECRITICAL  (preliminaryWindows 95)
PB_APMRESUMECRITICAL  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The PB_APMRESUMECRITICAL message is sent as a notification that the system has resumed operation after a critical suspension caused by a failing battery. A driver receives this message through the WM_POWERBROADCAST message.

Parameters

dwData

Reserved; must be 0.

Return Value

Returns TRUE.

Remarks

Because a critical suspension occurs without prior notification, resources and data previously available to a driver may not be present when the driver receives this message. The driver should attempt to restore its state to the best of its ability. While in a critical suspension, the system maintains the state of the DRAM and local hard disks, but may not maintain net connections. A driver may have to take action with respect to files that were open on the network prior to the critical suspension.

This message is not sent to applications.

See Also

WM_POWERBROADCAST


PB_APMRESUMESTANDBY  (preliminaryWindows 95)
PB_APMRESUMESTANDBY  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The PB_APMRESUMESTANDBY message is sent as a notification that the system has resumed operation after being placed in standby mode. A driver receives this message through the WM_POWERBROADCAST message.

Parameters

dwData

Reserved; must be 0.

Return Value

Returns TRUE.

Remarks

This message is not sent to applications.

See Also

WM_POWERBROADCAST


PB_APMRESUMESUSPEND  (preliminaryWindows 95)
PB_APMRESUMESUSPEND  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The PB_APMRESUMESUSPEND message is sent as a notification that the system has resumed opration after being suspended. A window receives this message through the WM_POWERBROADCAST message.

Parameters

dwData

Reserved; must be 0.

Return Value

Returns TRUE.

Remarks

Applications may receive this message at any time without a preceding PB_APMSUSPEND message.

See Also

PB_APMSUSPEND, WM_POWERBROADCAST


PB_APMSTANDBY  (preliminaryWindows 95)
PB_APMSTANDBY  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The PB_APMSTANDBY message is sent immediately before the system is placed in standby mode. This message is typically sent when all installable drivers have returned TRUE to a previous PB_APMQUERYSTANDBY message. A driver receives this message through the WM_POWERBROADCAST message. A window receives this message through the WM_POWERBROADCAST message.

Parameters

dwData

Reserved; must be 0.

Return Value

Returns TRUE.

Remarks

An installable driver should process this message by completing all tasks necessary to save data. Usually, no special action is required. This message may also be sent, without a prior PB_APMQUERYSUSPEND message, if an application or device driver uses the SetSystemPowerState function to force suspension.

This message is not sent to applications.

See Also

PB_APMQUERYSTANDBY, PB_APMQUERYSUSPEND, SetSystemPowerState, WM_POWERBROADCAST


PB_APMSUSPEND  (preliminaryWindows 95)
PB_APMSUSPEND  (preliminary−Windows 95)

dwData = (DWORD) lParam;

The PB_APMSUSPEND is sent immediately before the computer is suspended. This message is typically sent when all applications and installable drivers have returned TRUE to a previous PB_APMQUERYSUSPEND message. A window receives this message through the WM_POWERBROADCAST message.

Parameters

dwData

Reserved; must be 0.

Return Value

Returns TRUE.

Remarks

An application should process this message by completing all tasks necessary to save data. This message may also be sent, without a prior PB_APMQUERYSUSPEND message, if an application or device driver uses the SetSystemPowerState function to force suspension.

See Also

PB_APMQUERYSUSPEND, SetSystemPowerState, WM_POWERBROADCAST


PBM_DELTAPOS  (preliminaryWindows 95)
PBM_DELTAPOS  (preliminary−Windows 95)

PBM_DELTAPOS

wParam = (WPARAM) nIncrement

lParam = 0;

The PBM_DELTAPOS message advances the current position of a progress bar by a specified increment and redraws the bar to reflect the new position.

Parameters

nIncrement

Amount to advance the position.

Return Value

Returns the previous position.


PBM_SETPOS  (preliminaryWindows 95)
PBM_SETPOS  (preliminary−Windows 95)

PBM_SETPOS

wParam = (WPARAM) nNewPos;

lParam = 0;

The PBM_SETPOS message sets the current position for a progress bar and redraws the bar to reflect the new position.

Parameters

nNewPos

New position.

Return Value

Returns the previous position.


PBM_SETRANGE  (preliminaryWindows 95)
PBM_SETRANGE  (preliminary−Windows 95)

PBM_SETRANGE

wParam = 0;

lParam = MAKELPARAM(nMinRange, nMaxRange);

The PBM_SETRANGE message sets the minimum and maximum values for a progress bar and redraws the bar to reflect the new range.

Parameters

nMinRange

Minimum range value. By default, the minimum value is zero.

nMaxRange

Maximum range value. By default, the maximum value is 100.

Return Value

Returns the previous range values if successful, or zero otherwise. The low-order word specifies the previous minimum value, and the high-order word specifies the previous maximum value.


PBM_SETSTEP  (preliminaryWindows 95)
PBM_SETSTEP  (preliminary−Windows 95)

PBM_SETSTEP

wParam = (WPARAM) nStepInc;

lParam = 0;

The PBM_SETSTEP message specifies the step increment for a progress bar. The step increment is the amount by which the progress bar increases its current position whenever it receives a PBM_STEPIT message. By default, the step increment is set to 10.

Parameters

nStepInc

New step increment.

Return Value

Returns the previous step increment.

See Also

PBM_STEPIT


PBM_STEPIT  (preliminaryWindows 95)
PBM_STEPIT  (preliminary−Windows 95)

PBM_STEPIT

wParam = 0;

lParam = 0;

The PBM_STEPIT message advances the current position for a progress bar by the step increment and redraws the bar to reflect the new position. An application sets the step increment by sending the PBM_SETSTEP message.

Return Value

Returns the previous position.

Remarks

When the position exceeds the maximum range value, this message resets the current position so that the progress indicator starts over again from the beginning.

See Also

PBM_SETSTEP


PSM_ADDPAGE  (preliminaryWindows NT)
PSM_ADDPAGE  (preliminary−Windows NT)

PSM_ADDPAGE

wParam = 0;

lParam = (LPARAM) (HPROPSHEETPAGE) hpage);

// Corresponding macro

BOOL PropSheet_AddPage(hPropSheetDlg, hpage);

The PSM_ADDPAGE message adds a new page to the end of an existing property sheet.

Parameters

hPropSheetDlg

Handle to the property sheet.

hpage

Handle to the page to add. The page must have been created by a previous call to the CreatePropertySheetPage function.

Return Value

No return value.

Remarks

The property sheet is not resized to fit the new page. The new page should be no larger than the largest page currently in the property sheet.

See Also

CreatePropertySheetPage


PSM_APPLY  (preliminaryWindows NT)
PSM_APPLY  (preliminary−Windows NT)

PSM_APPLY

wParam = 0;

lParam = 0;

// Corresponding macro

BOOL PropSheet_Apply(hPropSheetDlg);

The PSM_APPLY message simulates the choice of the Apply Now button, indicating that one or more pages have changed and the changes need to be validated and recorded. The property sheet sends the PSN_KILLACTIVE notification message to the current page. If the current page returns FALSE, the property sheet sends the PSN_APPLY notification message to all pages.

Parameters

hPropSheetDlg

Handle to the property sheet.

Return Value

Returns TRUE if all pages successfully applied the changes or FALSE otherwise.

See Also

PSN_APPLY, PSN_KILLACTIVE


PSM_CANCELTOCLOSE  (preliminaryWindows NT)
PSM_CANCELTOCLOSE  (preliminary−Windows NT)

PSM_CANCELTOCLOSE

wParam = 0;

lParam = 0;

// Corresponding macro

VOID PropSheet_CancelToClose(hPropSheetDlg)

The PSM_CANCELTOCLOSE message disables the Cancel button and changes the text of the OK button to "Close." An application sends this message after applying a change that cannot be canceled.

Parameters

hPropSheetDlg

Handle to the property sheet.

Return Value

No return value.


PSM_CHANGED  (preliminaryWindows NT)
PSM_CHANGED  (preliminary−Windows NT)

PSM_CHANGED

wParam = (WPARAM) (HWND) hwndPage;

lParam = 0;

// Corresponding macro

BOOL PropSheet_Changed(hPropSheetDlg, hwndPage);

The PSM_CHANGED message informs a property sheet that information in a page has changed. The property sheet enables the Apply Now button.

Parameters

hPropSheetDlg

Handle to the property sheet.

hwndPage

Handle to the page that has changed.

Return Value

No return value.


PSM_GETTABCONTROL  (preliminaryWindows NT)
PSM_GETTABCONTROL  (preliminary−Windows NT)

PSM_GETTABCONTROL

wParam = 0;

lParam = 0;

// Corresponding macro

HWND PropSheet_GetTabControl(hPropSheetDlg);

The PSM_GETTABCONTROL message retrieves the handle to the tab control of a property sheet.

Parameters

hPropSheetDlg

Handle to the property sheet.

Return Value

Returns the handle to the tab control.


PSM_PRESSBUTTON  (preliminaryWindows NT)
PSM_PRESSBUTTON  (preliminary−Windows NT)

PSM_PRESSBUTTON

wParam = (WPARAM) (int) iButton;

lParam = 0;

// Corresponding macro

BOOL PropSheet_PressButton(hPropSheetDlg, iButton);

The PSM_PRESSBUTTON message simulates the choice of a property sheet button.

Parameters

hPropSheetDlg

Handle to the property sheet.

iButton

Index of button to choose. This parameter can be one of the following values:

Value	Meaning
PSBTN_APPLYNOW	Chooses the Apply Now button.
PSBTN_BACK	Chooses the Back button.
PSBTN_CANCEL	Chooses the Cancel button.
PSBTN_FINISH	Chooses the Finish button.
PSBTN_HELP	Chooses the Help button.
PSBTN_NEXT	Chooses the Next button.
PSBTN_OK	Chooses the OK button.
Return Value

No return value.


PSM_QUERYSIBLINGS  (preliminaryWindows NT)
PSM_QUERYSIBLINGS  (preliminary−Windows NT)

PSM_QUERYSIBLINGS

wParam = (WPARAM) param1;

lParam = (LPARAM) param2;

// Corresponding macro

int PropSheet_QuerySiblings(hPropSheetDlg, param1, param2);

The PSM_QUERYSIBLINGS message forwards the message to each page in the property sheet. If a page returns a nonzero value, the property sheet does not send the message to subsequent pages.

Parameters

hPropSheetDlg

Handle to the property sheet.

param1

First application-defined parameter.

param2

Second application-defined parameter.

Return Value

Returns the nonzero value from a page in the property sheet, or zero if no page returns a nonzero value.


PSM_REBOOTSYSTEM  (preliminaryWindows NT)
PSM_REBOOTSYSTEM  (preliminary−Windows NT)

PSM_REBOOTSYSTEM

wParam = 0;

lParam = 0;

// Corresponding macro

VOID PropSheet_RebootSystem(hPropSheetDlg);

The PSM_REBOOTSYSTEM message indicates that the system needs to be restarted for the changes to take effect. An application should send this message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message.

Parameters

hPropSheetDlg

Handle to the property sheet.

Return Value

No return value.

Remarks

This message causes the PropertySheet function to return the ID_PSREBOOTSYSTEM value, but only if the user chooses the OK button to close the property sheet. It is the application's responsibility to reboot the system, which can be done by using the ExitWindowsEx function.

This message supersedes all PSM_RESTARTWINDOWS messages that precede or follow it.

See Also

ExitWindowsEx, PropertySheet, PSN_APPLY, PSN_KILLACTIVE, PSM_RESTARTWINDOWS


PSM_REMOVEPAGE  (preliminaryWindows NT)
PSM_REMOVEPAGE  (preliminary−Windows NT)

PSM_REMOVEPAGE

wParam = (WPARAM) (int) index;

lParam = (LPARAM) (HPROPSHEETPAGE) hpage);

// Corresponding macro

VOID PropSheet_RemovePage(hPropSheetDlg, index, hpage);

The PSM_REMOVEPAGE message removes a page from a property sheet.

Parameters

hPropSheetDlg

Handle to the property sheet.

hpage and index

Handle to the page to remove, and the zero-based index of the page to remove. An application can specify the handle or the index, or both. If both are specified, hpage takes precedence.

Return Value

No return value.


PSM_RESTARTWINDOWS  (preliminaryWindows NT)
PSM_RESTARTWINDOWS  (preliminary−Windows NT)

PSM_RESTARTWINDOWS

wParam = 0;

lParam = 0;

// Corresponding macro

VOID PropSheet_RestartWindows(hPropSheetDlg);

The PSM_RESTARTWINDOWS message indicates that Windows needs to be restarted for the changes to take effect. An application should send this message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message.

Parameters

hPropSheetDlg

Handle to the property sheet.

Return Value

No return value.

Remarks

This message causes the PropertySheet function to return the ID_PSRESTARTWINDOWS value, but only if the user chooses the OK button to close the property sheet. It is the application's responsibility to restart Windows, which can be done by using the ExitWindowsEx function.

See Also

ExitWindowsEx, PropertySheet, PSN_APPLY, PSN_KILLACTIVE


PSM_SETCURSEL  (preliminaryWindows NT)
PSM_SETCURSEL  (preliminary−Windows NT)

PSM_SETCURSEL

wParam = (WPARAM) (int) index;

lParam = (LPARAM) (HPROPSHEETPAGE) hpage;

// Corresponding macro

BOOL PropSheet_SetCurSel(hPropSheetDlg, hpage, index);

The PSM_SETCURSEL message activates the given page in a property sheet.

Parameters

hPropSheetDlg

Handle to the property sheet.

hpage and index

Handle to the page to activate, and the zero-based index of the page to activate. An application can specify the handle or the index, or both. If both are specified, hpage takes precedence.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

See Also

PSN_KILLACTIVE, PSN_SETACTIVE


PSM_SETCURSELID  (preliminaryWindows NT)
PSM_SETCURSELID  (preliminary−Windows NT)

PSM_SETCURSELID

wParam = 0;

lParam = (LPARAM) (int) id;

// Corresponding macro

BOOL PropSheet_SetCurSelByID(hPropSheetDlg, id);

The PSM_SETCURSELID message activates the given page in a property sheet based on the resource identifier of the page.

Parameters

hPropSheetDlg

Handle to the property sheet.

id

Resource identifier of the page to activate.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

See Also

PSN_KILLACTIVE, PSN_SETACTIVE


PSM_SETFINISHTEXT  (preliminaryWindows NT)
PSM_SETFINISHTEXT  (preliminary−Windows NT)

PSM_SETFINISHTEXT

wParam = 0;

lParam = (LPARAM) (LPSTR) lpszText;

// Corresponding macro

VOID PropSheet_SetFinishText(hPropSheetDlg, lpszText);

The PSM_SETFINISHTEXT message sets the text of the Finish button in a wizard property sheet, shows and enables the button, and hides the Next and Back buttons.

Parameters

hPropSheetDlg

Handle to the property sheet.

lpszText

Pointer to the new text for the Finish button.

Return Value

No return value.

Remarks

This message causes the DM_SETDEFID message to be sent to the property sheet dialog box. The wParam parameter specifies the identifier of the Finish button.

See Also

DM_SETDEFID


PSM_SETTITLE  (preliminaryWindows NT)
PSM_SETTITLE  (preliminary−Windows NT)

PSM_SETTITLE

wParam = (WPARAM) (DWORD) dwStyle

lParam = (LPARAM) (LPCSTR) lpszText;

// Corresponding macro

VOID PropSheet_SetTitle(hPropSheetDlg, dwStyle, lpszText);

The PSM_SETTITLE message sets the title of a property sheet.

Parameters

hPropSheetDlg

Handle to the property sheet.

dwStyle

Flag that indicates whether to include the prefix "Properties for" with the specified title string. If dwStyle is the PSH_PROPTITLE value, the prefix is included. Otherwise, the prefix is not used.

lpszText

Pointer to a buffer that contains the title string. If the high-order word of this parameter is NULL, the property sheet loads the string resource specified in the low-order word.

Return Value

No return value.


PSM_SETWIZBUTTONS  (preliminaryWindows NT)
PSM_SETWIZBUTTONS  (preliminary−Windows NT)

PSM_SETWIZBUTTONS

wParam = 0;

lParam = (LPARAM) (DWORD) dwFlags;

// Corresponding macro

VOID PropSheet_SetWizButtons(hPropSheetDlg, dwFlags);

The PSM_SETWIZBUTTONS message enables the Back, Next, or Finish button in a wizard property sheet. The PropSheet_SetWizButtons macro posts the PSM_SETWIZBUTTONS message.

Parameters

hPropSheetDlg

Handle to the property sheet.

dwFlags

Buttons to enable. This parameter can be a combination of the following values:

Value	Meaning
PSWIZB_BACK	Back button
PSWIZB_NEXT	Next button
PSWIZB_FINISH	Finish button
Return Value

No return value.


PSM_UNCHANGED  (preliminaryWindows NT)
PSM_UNCHANGED  (preliminary−Windows NT)

PSM_UNCHANGED

wParam = (WPARAM) (HWND) hwndPage;

lParam = 0;

// Corresponding macro

VOID PropSheet_UnChanged(hPropSheetDlg, hwndPage);

The PSM_UNCHANGED message informs a property sheet that information in a page has reverted to the previously saved state. The property sheet disables the Apply Now button if no other pages have registered changes with the property sheet.

Parameters

hPropSheetDlg

Handle to the property sheet.

hwndPage

Handle to the page that has reverted to the previously saved state.

Return Value

No return value.


PSN_APPLY  (preliminaryWindows NT)
PSN_APPLY  (preliminary−Windows NT)

PSN_APPLY

lpnmhdr = (NMHDR FAR *) lParam;

The PSN_APPLY notification message indicates that the user chose the OK or Apply Now button and wants all changes to take effect. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Return Value

Returns the PSNRET_INVALID_NOCHANGEPAGE value to prevent the changes from taking effect and to return the focus to the page, or the PSNRET_NOERROR value to accept the changes and allow the property sheet to be destroyed.

Remarks

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

A page should not call the EndDialog function when processing this notification message.

The property sheet is destroyed if the user chooses the OK button and the application returns the PSNRET_NOERROR value in response to this notification.

To receive this notification, a page must set the DWL_MSGRESULT value to FALSE in response the PSN_KILLACTIVE notification message.

The PSHNOTIFY structure is supplied with the PSN_APPLY notification message. The lParam member in this structure is TRUE if the user clicked the Ok or Cancel button, and is FALSE if the user clicked the Close button.

See Also

EndDialog, NMHDR, PSN_KILLACTIVE, PSHNOTIFY, SetWindowLong, WM_NOTIFY


PSN_HELP  (preliminaryWindows NT)
PSN_HELP  (preliminary−Windows NT)

PSN_HELP

lpnmhdr = (NMHDR FAR *) lParam;

The PSN_HELP notification message notifies a page that the user has chosen the Help button. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Return Value

No return value.

Remarks

An application should display help information for the page.

See Also

NMHDR, WM_NOTIFY


PSN_KILLACTIVE  (preliminaryWindows NT)
PSN_KILLACTIVE  (preliminary−Windows NT)

PSN_KILLACTIVE

lpnmhdr = (NMHDR FAR *) lParam;

The PSN_KILLACTIVE notification message notifies a page that it is about to lose the activation either because another page is being activated or the user has chosen the OK button. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Return Value

Returns TRUE to prevent the page from losing the activation or FALSE to allow it.

Remarks

An application should validate the information that the user has typed.

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

If the dialog box procedure sets DWL_MSGRESULT to TRUE, it should display a message box to explain the problem to the user.

See Also

SetWindowLong, NMHDR, WM_NOTIFY


PSN_QUERYCANCEL  (preliminaryWindows NT)
PSN_QUERYCANCEL  (preliminary−Windows NT)

PSN_QUERYCANCEL

lpnmhdr = (NMHDR FAR *) lParam;

The PSN_QUERYCANCEL notification message indicates that the user chose the Cancel button. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle of the property sheet.

Return Value

Returns TRUE to prevent the cancel operation or FALSE to allow it.

Remarks

A property sheet page can use this notification message to ask the user to verify the cancel operation.

See Also

NMHDR, WM_NOTIFY


PSN_RESET  (preliminaryWindows NT)
PSN_RESET  (preliminary−Windows NT)

PSN_RESET

lpnmhdr = (NMHDR FAR *) lParam;

The PSN_RESET notification message notifies a page that the user has chosen the Cancel button and the property sheet is about to be destroyed. All changes made since the user last chose the Apply Now button are canceled. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle of the property sheet.

Return Value

No return value.

Remarks

An application can use this notification message as an opportunity to perform cleanup operations.

A page should not call the EndDialog function when processing this notification message.

The PSHNOTIFY structure is supplied with the PSN_RESET notification message. The lParam member in this structure is TRUE if the user clicked the Ok or Cancel button, and is FALSE if the user clicked the Close button.

See Also

EndDialog, NMHDR, PSHNOTIFY, WM_NOTIFY


PSN_SETACTIVE  (preliminaryWindows NT)
PSN_SETACTIVE  (preliminary−Windows NT)

PSN_SETACTIVE

lpnmhdr = (NMHDR FAR *) lParam;

The PSN_SETACTIVE notification message notifies a page that it is about to be activated. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

lpnmhdr

Pointer to the property sheet.

Return Value

Returns zero to accept the activation or −1 to activate the next or previous page (depending on whether the user chose the Next or Back button). To set the activation to a particular page, return the resource identifier of the page.

Remarks

The PSN_SETACTIVE notification message is sent before the page is visible. An application can use this notification to initialize data in the page.

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

See Also

NMHDR, SetWindowLong, WM_NOTIFY


PSN_WIZBACK  (preliminaryWindows NT)
PSN_WIZBACK  (preliminary−Windows NT)

PSN_WIZBACK

lpnmhdr = (NMHDR FAR *) lParam;

The PSN_WIZBACK notification message notifies a page that the user has chosen the Back button in a wizard property sheet. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle of the property sheet.

Return Value

Returns −1 to prevent the property sheet from advancing to the previous page.

See Also

NMHDR, WM_NOTIFY


PSN_WIZFINISH  (preliminaryWindows NT)
PSN_WIZFINISH  (preliminary−Windows NT)

PSN_WIZFINISH

lpnmhdr = (NMHDR FAR *) lParam;

The PSN_WIZFINISH notification message notifies a page that the user has chosen the Finish button in a wizard property sheet. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Return Value

Returns a nonzero value to prevent the property sheet from being destroyed.

See Also

NMHDR, WM_NOTIFY


PSN_WIZNEXT  (preliminaryWindows NT)
PSN_WIZNEXT  (preliminary−Windows NT)

PSN_WIZNEXT

lpnmhdr = (NMHDR FAR *) lParam;

The PSN_WIZNEXT notification message notifies a page that the user has chosen the Next button in a wizard property sheet. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

lpnmhdr

Pointer to an NMHDR structure. The hwndFrom member is the handle to the property sheet.

Return Value

Returns −1 to prevent the property sheet from advancing to the next page.

See Also

NMHDR, WM_NOTIFY


SB_GETBORDERS  (preliminaryWindows NT)
SB_GETBORDERS  (preliminary−Windows NT)

SB_GETBORDERS

wParam = 0;

lParam = (LPARAM) (LPINT) aBorders;

The SB_GETBORDERS message retrieves the current widths of the horizontal and vertical borders of a status window.

Parameters

aBorders

Pointer to an integer array that has three elements. The first element receives the width of the horizontal border, the second receives the width of the vertical border, and the third receives the width of the border between rectangles.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

The borders determine the spacing between the outside edge of the window and the rectangles within the window that contain text. The borders also determine the spacing between rectangles.


SB_GETPARTS  (preliminaryWindows NT)
SB_GETPARTS  (preliminary−Windows NT)

SB_GETPARTS

wParam = (WPARAM) nParts;

lParam = (LPARAM) (LPINT) aRightCoord;

The SB_GETPARTS message retrieves a count of the parts in a status window. The message also retrieves the coordinate of the right edge of the specified number of parts.

Parameters

nParts

Number of parts for which to retrieve coordinates. If this parameter is greater than the number of parts in the window, the message retrieves coordinates for existing parts only.

aRightCoord

Pointer to an integer array that has the same number of elements as parts specified by nParts. Each element in the array receives the client coordinate of the right edge of the corresponding part. If an element is set to − 1, the position of the right edge for that part extends to the right edge of the window. To retrieve the current number of parts, set this parameter to zero.

Return Value

Returns the number of parts in the window if successful or zero otherwise.


SB_GETRECT  (preliminaryWindows NT)
SB_GETRECT  (preliminary−Windows NT)

SB_GETRECT

wParam = (WPARAM) iPart;

lParam = (LPARAM) (LPRECT) lprc;

The SB_GETRECT message retrieves the bounding rectangle of a part in a status window.

Parameters

iPart

Zero-based index of the part whose bounding rectangle is to be retrieved.

lprc

Pointer to a RECT structure that receives the bounding rectangle.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

See Also

RECT


SB_GETTEXT  (preliminaryWindows NT)
SB_GETTEXT  (preliminary−Windows NT)

SB_GETTEXT

wParam = (WPARAM) iPart;

lParam = (LPARAM) (LPSTR) szText;

The SB_GETTEXT message retrieves the text from the specified part of a status window.

Parameters

iPart

Zero-based index of the part from which to retrieve text.

szText

Pointer to the buffer that receives the text. This parameter is a null-terminated string.

Return Value

Returns a 32-bit value that consists of two 16-bit values. The low word specifies the length, in characters, of the text. The high word specifies the type of operation used to draw the text. The type can be one of these values:

Value	Meaning
0	The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS	The text is drawn without borders.
SBT_POPOUT	The text is drawn with a border to appear higher than the plane of window.
If the text has the SBT_OWNERDRAW drawing type, this message returns the 32-bit value associated with the text instead of the length and operation type.


SB_GETTEXTLENGTH  (preliminaryWindows NT)
SB_GETTEXTLENGTH  (preliminary−Windows NT)

SB_GETTEXTLENGTH

wParam = (WPARAM) iPart;

lParam = 0;

The SB_GETTEXTLENGTH message retrieves the length, in characters, of the text from the specified part of a status window.

Parameters

iPart

Zero-based index of the part from which to retrieve text.

Return Value

Returns a 32-bit value that consists of two 16-bit values. The low word specifies the length, in characters, of the text. The high word specifies the type of operation used to draw the text. The type can be one of these values:

Value	Meaning
0	The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS	The text is drawn without borders.
SBT_OWNERDRAW	The text is drawn by the parent window.
SBT_POPOUT	The text is drawn with a border to appear higher than the plane of the window.


SB_SETMINHEIGHT  (preliminaryWindows NT)
SB_SETMINHEIGHT  (preliminary−Windows NT)

SB_SETMINHEIGHT

wParam = (WPARAM) minHeight;

lParam = 0;

The SB_SETMINHEIGHT message sets the minimum height of a status window's drawing area.

Parameters

minHeight

Minimum height, in pixels, of the window.

Return Value

No return value.

Remarks

The minimum height is the sum of wParam and twice the width, in pixels, of the vertical border of the status window. An application must send the WM_SIZE message to the status window to redraw the window. The wParam and lParam parameters of the WM_SIZE message should be set to zero.

See Also

WM_SIZE


SB_SETPARTS  (preliminaryWindows NT)
SB_SETPARTS  (preliminary−Windows NT)

SB_SETPARTS

wParam = (WPARAM) nParts;

lParam = (LPARAM) (LPINT) aWidths;

The SB_SETPARTS message sets the number of parts in a status window and the coordinate of the right edge of each part.

Parameters

nParts

Number of parts to set. The number of parts cannot be greater than 255.

aWidths

Pointer to an integer array that has the same number of elements as parts specified by nParts. Each element in the array specifies the position, in client coordinates, of the right edge of the corresponding part. If an element is  − 1, the position of the right edge for that part extends to the right edge of the window.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.


SB_SETTEXT  (preliminaryWindows NT)
SB_SETTEXT  (preliminary−Windows NT)

SB_SETTEXT

wParam = (WPARAM) iPart | uType;

lParam = (LPARAM) (LPSTR) szText;

The SB_SETTEXT message sets the text in the specified part of a status window.

Parameters

iPart

Zero-based index of the part to set. If this value is 255, the status window is assumed to be a simple window having only one part.

uType

Type of drawing operation. This parameter can be one of the following values:

Value	Meaning
0	The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS	The text is drawn without borders.
SBT_OWNERDRAW	The text is drawn by the parent window.
SBT_POPOUT	The text is drawn with a border to appear higher than the plane of the window.
szText

Pointer to a null-terminated string that specifies the text to set. If uType is SBT_OWNERDRAW, this parameter represents 32 bits of data. The parent window must interpret the data and draw the text when it receives the WM_DRAWITEM message.

Return Value

If the operation succeeds, the return value is TRUE.

If the operation fails, the return value is FALSE.

Remarks

The message invalidates the portion of the window that has changed, causing it to display the new text when the window next receives the WM_PAINT message.

See Also

WM_DRAWITEM, WM_PAINT


SB_SIMPLE  (preliminaryWindows NT)
SB_SIMPLE  (preliminary−Windows NT)

SB_SIMPLE

wParam = (WPARAM) (BOOL) fSimple;

lParam = 0;

The SB_SIMPLE message specifies whether a status window displays simple text or displays all window parts set by a previous SB_SETPARTS message.

Parameters

fSimple

Display type flag. If this parameter is TRUE, the window displays simple text. If it is FALSE, it displays multiple parts.

Return Value

Returns FALSE if an error occurs.

Remarks

If the status window is being changed from nonsimple to simple, or vice versa, the window is immediately redrawn.

See Also

SB_SETPARTS


SBM_ENABLE_ARROWS

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.

Parameters

fuArrowFlags

Specifies whether the scroll bar arrows are enabled or disabled and indicates which arrows are enabled or disabled. This parameter can be one of the following values:

Value	Meaning
ESB_DISABLE_BOTH	Disables both arrows on a scroll bar.
ESB_DISABLE_DOWN	Disables the down arrow on a vertical scroll bar.
ESB_DISABLE_LTUP	Disables the left arrow on a horizontal scroll bar or the up arrow on a vertical scroll bar.
ESB_DISABLE_LEFT	Disables the left arrow on a horizontal scroll bar.
ESB_DISABLE_RTDN	Disables the right arrow on a horizontal scroll bar or the down arrow on a vertical scroll bar.
ESB_DISABLE_UP	Disables the up arrow on a vertical scroll bar.
ESB_ENABLE_BOTH	Enables both arrows on a scroll bar.
Return Value

If the message succeeds, the return value is TRUE; otherwise, it is FALSE.


SBM_GETPOS

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.

Return Value

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

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.

Parameters

lpnMinPos

Points to a value that receives the minimum scrolling position.

lpnMaxPos

Points to a value that receives the maximum scrolling position.

Return Value

This message does not return a value.

See Also

SBM_GETPOS, SBM_SETPOS, SBM_SETRANGE, SBM_SETRANGEREDRAW


SBM_GETSCROLLINFO  (preliminaryWindows NT)
SBM_GETSCROLLINFO  [image]  (preliminary−Windows NT)

SBM_GETSCROLLINFO

wParam = 0;                             // not used, must be zero

lParam = (LPARAM) (LPSCROLLINFO) lpsi;  // scroll bar parameters

An application sends the SBM_GETSCROLLINFO message to retrieve the parameters of a scroll bar.

Parameters

lpsi

Value of lParam. Points to a SCROLLINFO structure whose fMask member, when the message is sent, specifies the scroll bar parameters to retrieve. Before returning, the message copies the specified parameters to the appropriate members of the structure.

The fMask member can be a combination of the following values:

Value	Meaning
SIF_ALL	Combination of SIF_PAGE, SIF_POS, and SIF_RANGE.
SIF_PAGE	Copies the scroll page to the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS	Copies the scroll position to the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE	Copies the scroll range to the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
Return Value

If the message retrieved any values, the return value is TRUE; otherwise, it is FALSE.

See Also

SBM_SETSCROLLINFO, SCROLLINFO


SBM_SETPOS

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.

Parameters

nPos

Specifies the new position of the scroll box. It must be within the scrolling range.

fRedraw

Specifies whether the scroll bar should be redrawn to reflect the new scroll box position. If this parameter is TRUE, the scroll bar is redrawn. If it is FALSE, the scroll bar is not redrawn.

Return Value

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Remarks

If the scroll bar control is redrawn by a subsequent call to another function, setting the fRedraw parameter to FALSE is useful.

See Also

SBM_GETPOS, SBM_GETRANGE, SBM_SETRANGE, SBM_SETRANGEREDRAW


SBM_SETRANGE

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.

Parameters

nMinPos

Specifies the minimum scrolling position.

fMaxPos

Specifies the maximum scrolling position.

Return Value

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Remarks

The default minimum and maximum position values are zero. The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than the value of MAXLONG.

If the minimum and maximum position values are equal, the scroll bar control is hidden and, in effect, disabled.

See Also

SBM_GETPOS, SBM_GETRANGE, SBM_SETPOS, SBM_SETRANGEREDRAW


SBM_SETRANGEREDRAW

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.

Parameters

nMinPos

Specifies the minimum scrolling position.

fMaxPos

Specifies the maximum scrolling position.

Return Value

If the position of the scroll box changed, the return value is the previous position of the scroll box; otherwise, it is zero.

Remarks

The default minimum and maximum position values are zero. The difference between the values specified by the nMinPos and nMaxPos parameters must not be greater than the value of MAXLONG.

If the minimum and maximum position values are equal, the scroll bar control is hidden and, in effect, disabled.

See Also

SBM_GETPOS, SBM_GETRANGE, SBM_SETPOS, SBM_SETRANGE


SBM_SETSCROLLINFO  (preliminaryWindows NT)
SBM_SETSCROLLINFO  [image]  (preliminary−Windows NT)

SBM_SETSCROLLINFO

wParam = (WPARAM) fRedraw;              // redraw flag

lParam = (LPARAM) (LPSCROLLINFO) lpsi;  // scroll bar parameters

An application sends the SBM_GETSCROLLINFO message to set the parameters of a scroll bar.

Parameters

fRedraw

Value of wParam. Specifies whether the scroll bar is redrawn to reflect the new scroll box position. If this parameter is TRUE, the scroll bar is redrawn. If it is FALSE, the scroll bar is not redrawn.

lpsi

Value of lParam. Points to a SCROLLINFO structure whose fMask member, when the message is sent, specifies the scroll bar parameters to set.

The fMask member can be a combination of the following values:

Value	Meaning
SIF_ALL	Combination of SIF_PAGE, SIF_POS, and SIF_RANGE.
SIF_PAGE	Sets the scroll page to the value specified in the nPage member of the SCROLLINFO structure pointed to by lpsi.
SIF_POS	Sets the scroll position to the value specified in the nPos member of the SCROLLINFO structure pointed to by lpsi.
SIF_RANGE	Sets the scroll range to the value specified in the nMin and nMax members of the SCROLLINFO structure pointed to by lpsi.
Return Value

The return value is the current position of the scroll box.

See Also

SBM_GETSCROLLINFO, SCROLLINFO


STM_GETICON

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 a static control that has the SS_ICON style.

Parameters

This message has no parameters.

Return Value

The return value is the handle of the icon, or NULL if either the static control has no associated icon or if an error occurred.

See Also

STM_SETICON


STM_GETIMAGE  (preliminaryWindows NT)
STM_GETIMAGE  (preliminary−Windows NT)

STM_GETIMAGE

wParam = (WPARAM) fImageType;  // image-type flag

lParam = 0;                    // not used; must be zero

An application sends an STM_GETIMAGE message to retrieve the handle of the image associated with a static control.

Parameters

fImageType

Value of wParam. Specifies the type of image to retrieve. This parameter can be one of the following values:

IMAGE_BITMAP

IMAGE_CURSOR

IMAGE_ENHMETAFILE

IMAGE_ICON

Return Value

The return value is the handle of the image, if any; otherwise, it is NULL.

See Also

STM_SETIMAGE


STM_SETICON

STM_SETICON

wParam = (WPARAM) (HICON) hicon;    // handle of the icon

lParam = 0;                         // not used; must be zero

An application sends the STM_SETICON message to associate an icon with an icon control.

Parameters

hicon

Value of wParam. Identifies the icon to associate with the icon control.

Return Value

The return value is the handle of the icon previously associated with the icon control, or zero if an error occurs.

See Also

LoadIcon, STM_GETICON


STM_SETIMAGE  (preliminaryWindows NT)
STM_SETIMAGE  (preliminary−Windows NT)

STM_SETIMAGE

wParam = (WPARAM) fImageType;       // image-type flag

lParam = (LPARAM) (HANDLE) hImage;  // handle of the image

An application sends an STM_SETIMAGE message to associate a new image (icon or bitmap) with a static control.

Parameters

fImageType

Value of wParam. Specifies the type if image to associate with the static control. This parameter can be one of the following values:

IMAGE_BITMAP

IMAGE_CURSOR

IMAGE_ENHMETAFILE

IMAGE_ICON

hImage

Value of lParam. Identifies the image to associate with the static control.

Return Value

The return value is the handle of the image previously associated with the static control, if any; otherwise, it is NULL.

See Also

STM_GETIMAGE


STN_CLICKED  (preliminaryWindows 95)
STN_CLICKED  [image]  (preliminary−Windows 95)

STN_CLICKED
idStatic = (int) LOWORD(wParam);    // identifier of static control
hwndStatic = (HWND) LOWORD(lParam); // handle of static control

The STN_CLICKED notification message is sent when the user clicks a static control that has the SS_NOTIFY style. The parent window of the control receives this notification message through the WM_COMMAND message.

See Also

STN_DBLCLK, WM_COMMAND


STN_DBLCLK  (preliminaryWindows 95)
STN_DBLCLK  [image]  (preliminary−Windows 95)

STN_DBLCLK
idStatic = (int) LOWORD(wParam);    // identifier of static control
hwndStatic = (HWND) LOWORD(lParam); // handle of static control

The STN_DBLCLK notification message is sent when the user double-clicks a static control that has the SS_NOTIFY style. The parent window of the control receives this notification message through the WM_COMMAND message.

See Also

STN_CLICKED, WM_COMMAND


STN_DISABLE  (preliminaryWindows 95)
STN_DISABLE  [image]  (preliminary−Windows 95)

STN_DISABLE
idStatic = (int) LOWORD(wParam);    // identifier of static control
hwndStatic = (HWND) LOWORD(lParam); // handle of static control

The STN_DISABLE notification message is sent when a static control is disabled. The static control must have the SS_NOTIFY style to receive this notification message. The parent window of the control receives this notification message through the WM_COMMAND message.

See Also

STN_ENABLE, WM_COMMAND


STN_ENABLE  (preliminaryWindows 95)
STN_ENABLE  [image]  (preliminary−Windows 95)

STN_ENABLE
idStatic = (int) LOWORD(wParam);    // identifier of static control
hwndStatic = (HWND) LOWORD(lParam); // handle of static control

The STN_ENABLE notification message is sent when a static control is enabled. The static control must have the SS_NOTIFY style to receive this notification message. The parent window of the control receives this notification message through the WM_COMMAND message.

See Also

STN_DISABLE, WM_COMMAND


TB_ADDBITMAP  (preliminaryWindows NT)
TB_ADDBITMAP  (preliminary−Windows NT)

TB_ADDBITMAP

wParam = (WPARAM) nButtons;

lParam = (LPARAM) (LPTBADDBITMAP) lptbab;

The TB_ADDBITMAP message adds one or more images to the list of button images available for a toolbar.

Parameters

nButtons

Number of button images in the bitmap.

lptbab

Pointer to a TBADDBITMAP structure that contains the identifier of a bitmap resource and the handle to the module instance with the executable file that contains the bitmap resource.

Return Value

Returns the index of the first new image if successful or  − 1 otherwise.

Remarks

If the toolbar was created by using the CreateWindowEx function, you must send the TB_BUTTONSTRUCTSIZE message to the toolbar before sending TB_ADDBITMAP.

See Also

CreateWindowEx, TBADDBITMAP, TB_BUTTONSTRUCTSIZE


TB_ADDBUTTONS  (preliminaryWindows NT)
TB_ADDBUTTONS  (preliminary−Windows NT)

TB_ADDBUTTONS

wParam = (WPARAM) (UINT) uNumButtons;

lParam = (LPARAM) (LPTBBUTTON) lpButtons;

The TB_ADDBUTTONS message adds one or more buttons to a toolbar.

Parameters

uNumButtons

Number of buttons to add.

lpButtons

Pointer to an array of TBBUTTON structures that contains information about the buttons to add. There must be the same number of elements in the array as buttons specified by uNumButtons.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

If the toolbar was created by using the CreateWindowEx function, you must send the TB_BUTTONSTRUCTSIZE message to the toolbar before sending TB_ADDBUTTONS.

See Also

CreateWindowEx, TBBUTTON, TB_BUTTONSTRUCTSIZE


TB_ADDSTRING  (preliminaryWindows NT)
TB_ADDSTRING  (preliminary−Windows NT)

TB_ADDSTRING

wParam = (WPARAM) (HINSTANCE) hinst;

lParam = (LPARAM) MAKELONG(idString, 0);

The TB_ADDSTRING message adds a new string to the list of strings available for a toolbar.

Parameters

hinst

Handle to the module instance with an executable file that contains the string resource. If idString points to one or more strings to add, this parameter is zero.

idString

Resource identifier for the string resource, or the address of a buffer that contains one or more null-terminated strings to add to the list, depending on the value of hinst. The last string must be terminated with two null characters.

Return Value

Returns the index of the first new string if successful or  − 1 otherwise.


TB_AUTOSIZE  (preliminaryWindows NT)
TB_AUTOSIZE  (preliminary−Windows NT)

TB_AUTOSIZE

wParam = 0;

lParam = 0;

The TB_AUTOSIZE message causes a toolbar to be resized.

Return Value

No return value.

Remarks

An application sends the TB_AUTOSIZE message after causing the size of a toolbar to change either by setting the button or bitmap size or by adding strings for the first time.


TB_BUTTONCOUNT  (preliminaryWindows NT)
TB_BUTTONCOUNT  (preliminary−Windows NT)

TB_BUTTONCOUNT

wParam = 0;

lParam = 0;

The TB_BUTTONCOUNT message retrieves a count of the buttons currently in the toolbar.

Return Value

Returns the count of the buttons.


TB_BUTTONSTRUCTSIZE  (preliminaryWindows NT)
TB_BUTTONSTRUCTSIZE  (preliminary−Windows NT)

wParam = (WPARAM) cb;

lParam = 0;

The TB_BUTTONSTRUCTSIZE message specifies the size of the TBBUTTON structure.

Parameters

cb

Size, in bytes, of the TBBUTTON structure.

The system uses the size to determine which version of the common control dynamic-link library (DLL) is being used.

If an application uses the CreateWindowEx function to create the toolbar, the application must send this message to the toolbar before sending the TB_ADDBITMAP or TB_ADDBUTTONS message. The CreateToolBarEx function automatically sends TB_BUTTONSTRUCTSIZE, and the size of the TBBUTTON structure is a parameter of the function.

Return Value

No return value.

See Also

CreateWindowEx, TB_ADDBITMAP, TB_ADDBUTTONS, TBBUTTON


TB_CHANGEBITMAP  (preliminaryWindows NT)
TB_CHANGEBITMAP  (preliminary−Windows NT)

TB_CHANGEBITMAP

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELPARAM(iBitmap, 0);

The TB_CHANGEBITMAP message changes the bitmap for a button in a toolbar.

Parameters

idButton

Command identifier of the button that is to receive a new bitmap.

iBitmap

Zero-based index of an image in the toolbar's image list. The system displays the specified image in the button.

Return Value

Returns TRUE if successful or FALSE otherwise.


TB_CHECKBUTTON  (preliminaryWindows NT)
TB_CHECKBUTTON  (preliminary−Windows NT)

TB_CHECKBUTTON

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fCheck, 0);

The TB_CHECKBUTTON message checks or unchecks a given button in a toolbar.

Parameters

idButton

Command identifier of the button to check.

fCheck

Check flag. If this parameter TRUE, the check is added. If it is FALSE, the check is removed.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

When a button has been checked, it appears to have been pressed.


TB_COMMANDTOINDEX  (preliminaryWindows NT)
TB_COMMANDTOINDEX  (preliminary−Windows NT)

TB_COMMANDTOINDEX

wParam = (WPARAM) idButton;

lParam = 0;

The TB_COMMANDTOINDEX message retrieves the zero-based index for the button associated with the specified command identifier.

Parameters

idButton

Command identifier associated with the button.

Return Value

Returns the zero-based index for the button.


TB_CUSTOMIZE  (preliminaryWindows NT)
TB_CUSTOMIZE  (preliminary−Windows NT)

TB_CUSTOMIZE

wParam = 0;

lParam = 0;

The TB_CUSTOMIZE message displays the Customize Toolbar dialog box.

Return Value

No return value.


TB_DELETEBUTTON  (preliminaryWindows NT)
TB_DELETEBUTTON  (preliminary−Windows NT)

TB_DELETEBUTTON

wParam = (WPARAM) iButton;

lParam = 0;

The TB_DELETEBUTTON message deletes a button from the toolbar.

Parameters

iButton

Zero-based index of the button to delete.

Return Value

Returns TRUE if successful or FALSE otherwise.


TB_ENABLEBUTTON  (preliminaryWindows NT)
TB_ENABLEBUTTON  (preliminary−Windows NT)

TB_ENABLEBUTTON

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fEnable, 0);

The TB_ENABLEBUTTON message enables or disables the specified button in a toolbar.

Parameters

idButton

Command identifier of the button to enable or disable.

fEnable

Enable flag. If this parameter is TRUE, the button is enabled. If it is FALSE, the button is disabled.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

When a button has been enabled, it can be pressed and checked.


TB_GETBITMAP  (preliminaryWindows NT)
TB_GETBITMAP  (preliminary−Windows NT)

TB_GETBITMAP

wParam = (WPARAM) idButton;

lParam = 0;

The TB_GETBITMAP message retrieves the index of the bitmap associated with a button in a toolbar.

Parameters

idButton

Command identifier of the button whose bitmap index is to be retrieved.

Return Value

Returns TRUE if successful or FALSE otherwise.


TB_GETBITMAPFLAGS  (preliminaryWindows NT)
TB_GETBITMAPFLAGS  (preliminary−Windows NT)

TB_GETBITMAPFLAGS

wParam = 0;

lParam = 0;

The TB_GETBITMAPFLAGS message retrieves the bitmap flags.

Return Value

Returns the TBBF_LARGE value if the display can handle large bitmaps (that is, if the width of the display has at least 120 pixels per logical inch). Otherwise, the return value is zero.


TB_GETBUTTON  (preliminaryWindows NT)
TB_GETBUTTON  (preliminary−Windows NT)

TB_GETBUTTON

wParam = (WPARAM) iButton;

lParam = (LPARAM) (LPTBBUTTON) lpButton;

The TB_GETBUTTON message retrieves information about the specified button in a toolbar.

Parameters

iButton

Zero-based index of the button for which to retrieve information.

lpButton

Pointer to the TBBUTTON structure that receives the button information.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

TBBUTTON


TB_GETBUTTONTEXT  (preliminaryWindows NT)
TB_GETBUTTONTEXT  (preliminary−Windows NT)

TB_GETBUTTONTEXT

wParam = (WPARAM) idButton;

lParam = (LPARAM) (LPSTR) lpszText;

The TB_GETBUTTONTEXT message retrieves the text of a button in a toolbar.

Parameters

idButton

Command identifier of the button whose text is to be retrieved.

lpszText

Pointer to a buffer that receives the button text.

Return Value

Returns the length, in characters, of the string copied to the specified buffer if successful. The length does not include the terminating null character. Otherwise, the return value is  − 1.


TB_GETITEMRECT  (preliminaryWindows NT)
TB_GETITEMRECT  (preliminary−Windows NT)

wParam = (WPARAM) iButton;

lParam = (LPARAM) (LPRECT) lprc;

The TB_GETITEMRECT message retrieves the bounding rectangle of a button in a toolbar.

Parameters

iButton

Zero-based index of the button for which to retrieve information.

lprc

Pointer to a RECT structure that receives the coordinates of the bounding rectangle.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

This message does not retrieve the bounding rectangle for buttons whose state is set to the TBSTATE_HIDDEN value.

See Also

RECT


TB_GETROWS  (preliminaryWindows NT)
TB_GETROWS  (preliminary−Windows NT)

TB_GETROWS

wParam = 0;

lParam = 0;

The TB_GETROWS message retrieves the number of rows of buttons in a toolbar with the TBSTYLE_WRAPABLE style.

Return Value

Returns the number of rows.


TB_GETSTATE  (preliminaryWindows NT)
TB_GETSTATE  (preliminary−Windows NT)

TB_GETSTATE

wParam = (WPARAM) idButton;

lParam = 0;

The TB_GETSTATE message retrieves information about the state of the specified button in a toolbar, such as whether it is enabled, pressed, or checked.

Parameters

idButton

Command identifier of the button for which to retrieve information.

Return Value

Returns the button state information if successful or  − 1 otherwise. The button state information can be a combination of the values listed in Button States.


TB_GETTOOLTIPS  (preliminaryWindows NT)
TB_GETTOOLTIPS  (preliminary−Windows NT)

TB_GETTOOLTIPS

wParam = 0;

lParam = 0;

The TB_GETTOOLTIPS message retrieves the handle to the tooltip control, if any, associated with the toolbar.

Return Value

Returns the handle to the tooltip control or NULL if the toolbar has no associated tooltip.


TB_HIDEBUTTON  (preliminaryWindows NT)
TB_HIDEBUTTON  (preliminary−Windows NT)

TB_HIDEBUTTON

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fShow, 0);

The TB_HIDEBUTTON message hides or shows the specified button in a toolbar.

Parameters

idButton

Command identifier of the button to hide or show.

fShow

Show flag. If this parameter is TRUE, the button is hidden. If it is FALSE, the button is shown.

Return Value

Returns TRUE if successful or FALSE otherwise.


TB_INDETERMINATE  (preliminaryWindows NT)
TB_INDETERMINATE  (preliminary−Windows NT)

TB_INDETERMINATE

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fIndeterminate, 0);

The TB_INDETERMINATE message sets or clears the indeterminate state of the specified button in a toolbar.

Parameters

idButton

Command identifier of the button whose indeterminate state is to be set or cleared.

fIndeterminate

Indeterminate flag. If this parameter is TRUE, the indeterminate state is set. If it is FALSE, the state is cleared.

Return Value

Returns TRUE if successful or FALSE otherwise.


TB_INSERTBUTTON  (preliminaryWindows NT)
TB_INSERTBUTTON  (preliminary−Windows NT)

TB_INSERTBUTTON

wParam = (WPARAM) iButton;

lParam = (LPARAM) (LPTBBUTTON) lpButton;

The TB_INSERTBUTTON message inserts a button in a toolbar.

Parameters

iButton

Zero-based index of a button. The message inserts the new button to the left of this button.

lpButton

Pointer to a TBBUTTON structure containing information about the button to insert.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

TBBUTTON


TB_ISBUTTONCHECKED  (preliminaryWindows NT)
TB_ISBUTTONCHECKED  (preliminary−Windows NT)

TB_ISBUTTONCHECKED

wParam = (WPARAM) idButton;

lParam = 0;

The TB_ISBUTTONCHECKED message determines whether the specified button in a toolbar is checked.

Parameters

idButton

Command identifier of the button.

Return Value

Returns nonzero if the button is checked or zero otherwise.


TB_ISBUTTONENABLED  (preliminaryWindows NT)
TB_ISBUTTONENABLED  (preliminary−Windows NT)

TB_ISBUTTONENABLED

wParam = (WPARAM) idButton;

lParam = 0;

The TB_ISBUTTONENABLED message determines whether the specified button in a toolbar is enabled.

Parameters

idButton

Command identifier of the button.

Return Value

Returns nonzero if the button is enabled or zero otherwise.


TB_ISBUTTONHIDDEN  (preliminaryWindows NT)
TB_ISBUTTONHIDDEN  (preliminary−Windows NT)

TB_ISBUTTONHIDDEN

wParam = (WPARAM) idButton;

lParam = 0;

The TB_ISBUTTONHIDDEN message determines whether the specified button in a toolbar is hidden.

Parameters

idButton

Command identifier of the button.

Return Value

Returns nonzero if the button is hidden or zero otherwise.


TB_ISBUTTONINDETERMINATE  (preliminaryWindows NT)
TB_ISBUTTONINDETERMINATE  (preliminary−Windows NT)

TB_ISBUTTONINDETERMINATE

wParam = (WPARAM) idButton;

lParam = 0;

The TB_ISBUTTONINDETERMINATE message determines whether the specified button in a toolbar is indeterminate.

Parameters

idButton

Command identifier of the button.

Return Value

Returns nonzero if the button is indeterminate or zero otherwise.


TB_ISBUTTONPRESSED  (preliminaryWindows NT)
TB_ISBUTTONPRESSED  (preliminary−Windows NT)

TB_ISBUTTONPRESSED

wParam = (WPARAM) idButton;

lParam = 0;

The TB_ISBUTTONPRESSED message determines whether the specified button in a toolbar is pressed.

Parameters

idButton

Command identifier of the button.

Return Value

Returns nonzero if the button is pressed or zero otherwise.


TB_PRESSBUTTON  (preliminaryWindows NT)
TB_PRESSBUTTON  (preliminary−Windows NT)

TB_PRESSBUTTON

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fPress, 0);

The TB_PRESSBUTTON message presses or releases the specified button in a toolbar.

Parameters

idButton

Command identifier of the button to press or release.

fPress

Press flag. If this parameter is TRUE, the button is pressed. If it is FALSE, the button is released.

Return Value

Returns TRUE if successful or FALSE otherwise.


TB_SAVERESTORE  (preliminaryWindows NT)
TB_SAVERESTORE  (preliminary−Windows NT)

TB_SAVERESTORE

wParam = (WPARAM) (BOOL) fSave;

lParam = (LPARAM)  (TBSAVEPARAMS *)ptbsp;

The TB_SAVERESTORE message saves or restores the state of the toolbar.

Parameters

fSave

Save or restore flag. If this parameter is TRUE, the information is saved. If it is FALSE, it is restored.

ptbsp

Pointer to a TBSAVEPARAMS structure that specifies the registry key, subkey, and value name for the toolbar state information.

Return Value

No return value.

See Also

TBSAVEPARAMS


TB_SETBITMAPSIZE  (preliminaryWindows NT)
TB_SETBITMAPSIZE  (preliminary−Windows NT)

TB_SETBITMAPSIZE

wParam = 0;

lParam = (LPARAM) MAKELONG(dxBitmap, dyBitmap)

The TB_SETBITMAPSIZE message sets the size of the bitmapped images to be added to a toolbar.

Parameters

dxBitmap

Width, in pixels, of the bitmapped images.

dyBitmap

Height, in pixels, of the bitmapped images.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

The size can be set only before adding any bitmaps to the toolbar. If an application does not explicitly set the bitmap size, the size defaults to 16 by 15 pixels.


TB_SETBUTTONSIZE  (preliminaryWindows NT)
TB_SETBUTTONSIZE  (preliminary−Windows NT)

TB_SETBUTTONSIZE

wParam = 0;

lParam = (LPARAM) MAKELONG(dxButton, dyButton)

The TB_SETBUTTONSIZE sets the size of the buttons to be added to a toolbar.

Parameters

dxButton

Width, in pixels, of the buttons.

dyButton

Height, in pixels, of the buttons.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

The size can be set only before adding any buttons to the toolbar. If an application does not explicitly set the button size, the size defaults to 24 by 22 pixels.


TB_SETCMDID  (preliminaryWindows NT)
TB_SETCMDID  (preliminary−Windows NT)

TB_SETCMDID

wParam = (WPARAM) (UINT) index;

lParam = (WPARAM) (UINT) cmdId;

The TB_SETCMDID message sets the command identifier of a toolbar button.

Parameters

index

Zero-based index of the button whose command identifier is to be set.

cmdId

Command identifier.

Return Value

Returns TRUE if successful or FALSE otherwise.


TB_SETPARENT  (preliminaryWindows NT)
TB_SETPARENT  (preliminary−Windows NT)

TB_SETPARENT

wParam = (WPARAM) (HWND) hwndParent;

lParam = 0;

The TB_SETPARENT message sets the parent window for a toolbar.

Parameters

hwndParent

Handle to the new parent window.

Return Value

No return value.


TB_SETROWS  (preliminaryWindows NT)
TB_SETROWS  (preliminary−Windows NT)

TB_SETROWS

wParam = (WPARAM) MAKEWPARAM(cRows, fLarger);

lParam = (LPARAM) (LPRECT) lprc;

The TB_SETROWS message sets the number of rows of buttons in a toolbar.

Parameters

cRows

Number of rows requested. The minimum number of rows is one, and the maximum is equal to the number of buttons in the toolbar.

fLarger

Flag that indicates whether to create more rows than requested when the system cannot create the number of rows specified by cRows. If this parameter is TRUE, the system creates more rows. If it is FALSE, the system creates fewer rows.

lprc

Pointer to a RECT structure that receives the bounding rectangle of the toolbar after the rows are set.

Return Value

No return value.

Remarks

Because the system does not break up button groups when setting the number of rows, the resulting number of rows might differ from the number requested.

See Also

RECT


TB_SETSTATE  (preliminaryWindows NT)
TB_SETSTATE  (preliminary−Windows NT)

TB_SETSTATE

wParam = (WPARAM) idButton;

lParam = (LPARAM) MAKELONG(fState, 0);

The TB_SETSTATE message sets the state for the specified button in a toolbar.

Parameters

idButton

Command identifier of the button.

fState

State flags. This parameter can be a combination of the values listed in Toolbar Constants.

Return Value

Returns TRUE if successful or FALSE otherwise.


TB_SETTOOLTIPS  (preliminaryWindows NT)
TB_SETTOOLTIPS  (preliminary−Windows NT)

TB_SETTOOLTIPS

wParam = (WPARAM) (HWND) hwndToolTip;

lParam = 0;

The TB_SETTOOLTIPS message associates a tooltip control with a toolbar.

Parameters

hwndToolTip

Handle to the tooltip control.

Return Value

No return value.

Remarks

Any buttons added to a toolbar before sending the TB_SETTOOLTIPS message are not registered with the tooltip control.


TBM_CLEARSEL  (preliminaryWindows NT)
TBM_CLEARSEL  (preliminary−Windows NT)

TBM_CLEARSEL

wParam = (WPARAM) (BOOL) fRedraw;

lParam = 0;

The TBM_CLEARSEL message clears the current selection in a trackbar.

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the trackbar is redrawn after the selection is cleared.

Return Value

No return value.


TBM_CLEARTICS  (preliminaryWindows NT)
TBM_CLEARTICS  (preliminary−Windows NT)

TBM_CLEARTICS

wParam = (WPARAM) (BOOL) fRedraw;

lParam = 0;

The TBM_CLEARTICS message removes the current tick marks from a trackbar.

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the trackbar is redrawn after the tick marks are cleared.

Return Value

No return value.


TBM_GETCHANNELRECT  (preliminaryWindows NT)
TBM_GETCHANNELRECT  (preliminary−Windows NT)

TBM_GETCHANNELRECT
wParam = 0;

lParam = (LPARAM) (LPRECT) lprc;

The TBM_GETCHANNELRECT message retrieves the size and position of the bounding rectangle for a trackbar's channel. (The channel is the area over which the slider moves and which contains the highlight when a range is selected.)

Parameters

lprc

Pointer to a RECT structure that contains the size and position of the channel's bounding rectangle when the function returns.

Return Value

No return value.

See Also

RECT


TBM_GETLINESIZE  (preliminaryWindows NT)
TBM_GETLINESIZE  (preliminary−Windows NT)

TBM_GETLINESIZE
wParam = 0;

lParam = 0;

The TBM_GETLINESIZE message retrieves the size of the line for a trackbar. The line size affects how much the slider moves for the TB_LINEUP and TB_LINEDOWN notification messages.

Return Value

Returns a 32-bit value that specifies the size of a line for the trackbar.

Remarks

The default setting for the line size is 1.


TBM_GETNUMTICS  (preliminaryWindows NT)
TBM_GETNUMTICS  (preliminary−Windows NT)

TBM_GETNUMTICS
wParam = 0;

lParam = 0;

The TBM_GETNUMTICS message retrieves the number of tick marks in a trackbar.

Return Value

Returns the number of tick marks.

Remarks

This message returns all of the tick marks, including the first and last tick marks created by the trackbar.


TBM_GETPAGESIZE  (preliminaryWindows NT)
TBM_GETPAGESIZE  (preliminary−Windows NT)

TBM_GETPAGESIZE
wParam = 0;

lParam = 0;

The TBM_GETPAGESIZE message retrieves the size of the page for a trackbar. The page size affects how much the slider moves for the TB_PAGEUP and TB_PAGEDOWN notification messages.

Return Value

Returns a 32-bit value that specifies the size of a page for the trackbar.


TBM_GETPOS  (preliminaryWindows NT)
TBM_GETPOS  (preliminary−Windows NT)

TBM_GETPOS

wParam = 0;

lParam = 0;

The TBM_GETPOS message retrieves the current position of the slider in a trackbar.

Return Value

Returns a 32-bit value that specifies the current position.


TBM_GETPTICS  (preliminaryWindows NT)
TBM_GETPTICS  (preliminary−Windows NT)

TBM_GETPTICS

wParam = 0;

lParam = 0;

The TBM_GETPTICS message retrieves the pointer to the array that contains the positions of tick marks for a trackbar.

Return Value

Returns the pointer to the array.


TBM_GETRANGEMAX  (preliminaryWindows NT)
TBM_GETRANGEMAX  (preliminary−Windows NT)

TBM_GETRANGEMAX

wParam = 0;

lParam = 0;

The TBM_GETRANGEMAX message retrieves the maximum position for the slider in a trackbar.

Return Value

Returns a 32-bit value that specifies the maximum position.


TBM_GETRANGEMIN  (preliminaryWindows NT)
TBM_GETRANGEMIN  (preliminary−Windows NT)

TBM_GETRANGEMIN

wParam = 0;

lParam = 0;

The TBM_GETRANGEMIN message retrieves the minimum position for the slider in a trackbar.

Return Value

Returns a 32-bit value that specifies the minimum position.


TBM_GETSELEND  (preliminaryWindows NT)
TBM_GETSELEND  (preliminary−Windows NT)

TBM_GETSELEND

wParam = 0;

lParam = 0;

The TBM_GETSELEND message retrieves the ending position of the current selection in a trackbar.

Return Value

Returns a 32-bit value that specifies the ending position of the current selection.


TBM_GETSELSTART  (preliminaryWindows NT)
TBM_GETSELSTART  (preliminary−Windows NT)

TBM_GETSELSTART

wParam = 0;

lParam = 0;

The TBM_GETSELSTART message retrieves the starting position of the current selection in a trackbar.

Return Value

Returns a 32-bit value that specifies the starting position of the current selection.


TBM_GETTHUMBLENGTH  (preliminaryWindows NT)
TBM_GETTHUMBLENGTH  (preliminary−Windows NT)

TBM_GETTHUMBLENGTH

wParam = 0;

lParam = 0;

The TBM_GETTHUMBLENGTH message retrieves the length of the slider in a trackbar.

Return Value

Returns the length, in pixels, of the slider.


TBM_GETTHUMBRECT  (preliminaryWindows NT)
TBM_GETTHUMBRECT  (preliminary−Windows NT)

TBM_GETTHUMBRECT

wParam = 0;

lParam = (LPARAM) (LPRECT) lprc;

The TBM_GETTHUMBRECT message retrieves the size and position of the bounding rectangle for the slider in a trackbar.

Parameters

lprc

Pointer to a RECT structure that contains the bounding rectangle for the slider when the function returns.

Return Value

No return value.

See Also

RECT


TBM_GETTIC  (preliminaryWindows NT)
TBM_GETTIC  (preliminary−Windows NT)

TBM_GETTIC

wParam = (WPARAM) (WORD) iTic;

lParam = 0;

The TBM_GETTIC message retrieves the position of a tick mark in a trackbar.

Parameters

iTic

Zero-based index identifying a tick mark.

Return Value

Returns the position of the specified tick mark or  − 1 if iTic does not specify a valid index.


TBM_GETTICPOS  (preliminaryWindows NT)
TBM_GETTICPOS  (preliminary−Windows NT)

TBM_GETTICPOS

wParam = (WPARAM) (WORD) iTic;

lParam = 0;

The TBM_GETTICPOS message retrieves the current physical position of a tick mark in a trackbar.

Parameters

iTic

Zero-based index identifying a tick mark.

Return Value

Returns the physical position, in client coordinates, of the specified tick mark or − 1 if iTic does not specify a valid index.


TBM_SETLINESIZE  (preliminaryWindows NT)
TBM_SETLINESIZE  (preliminary−Windows NT)

TBM_SETLINESIZE
wParam = 0;

lParam = (LONG) lLineSize;

The TBM_SETLINESIZE message sets the size of the line for a trackbar. The line size affects how much the slider moves for the TB_LINEUP and TB_LINEDOWN notification messages.

Parameters

lLineSize

New line size.

Return Value

Returns a 32-bit value that specifies the previous line size.


TBM_SETPAGESIZE  (preliminaryWindows NT)
TBM_SETPAGESIZE  (preliminary−Windows NT)

TBM_SETPAGESIZE
wParam = 0;

lParam = (LONG) lPageSize;

The TBM_SETPAGESIZE message sets the size of the page for a trackbar. The page size affects how much the slider moves for the TB_PAGEUP and TB_PAGEDOWN notification messages.

Parameters

lPageSize

New page size.

Return Value

Returns a 32-bit value that specifies the previous page size.


TBM_SETPOS  (preliminaryWindows NT)
TBM_SETPOS  (preliminary−Windows NT)

TBM_SETPOS

wParam = (WPARAM) (BOOL) fPosition;

lParam = (LPARAM) (LONG) lPosition;

The TBM_SETPOS message sets the current position of the slider in a trackbar.

Parameters

fPosition

Position flag. If this parameter is TRUE, the message sets the slider to the position given by lPosition. Otherwise, the message ensures that the current position is within the current minimum and maximum positions, but it does not move the slider.

lPosition

New position of the slider.

Return Value

No return value.


TBM_SETRANGE  (preliminaryWindows NT)
TBM_SETRANGE  (preliminary−Windows NT)

TBM_SETRANGE

wParam = (WPARAM) (BOOL) fRedraw;

lParam = (LPARAM) MAKELONG(lMinimum, lMaximum);

The TBM_SETRANGE message sets the range (minimum and maximum positions) for the slider in a trackbar.

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the range is set.

lMinimum

Minimum position for the slider.

lMaximum

Maximum position for the slider.

Return Value

No return value.


TBM_SETRANGEMAX  (preliminaryWindows NT)
TBM_SETRANGEMAX  (preliminary−Windows NT)

TBM_SETRANGEMAX

wParam = (WPARAM) fRedraw;

lParam = (LPARAM) lMaximum;

The TBM_SETRANGEMAX message sets the maximum position for the slider in a trackbar.

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the range is set.

lMaximum

Maximum position for the slider.

Return Value

No return value.


TBM_SETRANGEMIN  (preliminaryWindows NT)
TBM_SETRANGEMIN  (preliminary−Windows NT)

TBM_SETRANGEMIN

wParam = (WPARAM) fRedraw;

lParam = (LPARAM) lMinimum;

The TBM_SETRANGEMIN message sets the minimum position for the slider in a trackbar.

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the range is set.

lMinimum

Minimum position for the slider.

Return Value

No return value.


TBM_SETSEL  (preliminaryWindows NT)
TBM_SETSEL  (preliminary−Windows NT)

TBM_SETSEL

wParam = (WPARAM) (BOOL) fRedraw;

lParam = (LPARAM) MAKELONG(lMinimum, lMaximum);

The TBM_SETSEL message sets the starting and ending positions for the current selection in a trackbar.

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the selection is set.

lMinimum

Starting position for the slider.

lMaximum

Ending position for the slider.

Return Value

No return value.


TBM_SETSELEND  (preliminaryWindows NT)
TBM_SETSELEND  (preliminary−Windows NT)

TBM_SETSELEND

wParam = (WPARAM) (BOOL) fRedraw;

lParam = (LPARAM) (LONG) lEnd;

The TBM_SETSELEND message sets the ending position of the current selection in a trackbar.

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the selection is set.

lEnd

Ending position of the selection.

Return Value

No return value.


TBM_SETSELSTART  (preliminaryWindows NT)
TBM_SETSELSTART  (preliminary−Windows NT)

TBM_SETSELSTART

wParam = (WPARAM) (BOOL) fRedraw;

lParam = (LPARAM) (LONG) lStart;

The TBM_SETSELSTART message sets the starting position of the current selection in a trackbar.

Parameters

fRedraw

Redraw flag. If this parameter is TRUE, the slider is redrawn after the selection is set.

lStart

Starting position of the selection.

Return Value

No return value.


TBM_SETTHUMBLENGTH  (preliminaryWindows NT)
TBM_SETTHUMBLENGTH  (preliminary−Windows NT)

TBM_SETTHUMBLENGTH

wParam = (WPARAM) (UINT) iLength;

lParam = 0;

The TBM_SETTHUMBLENGTH message sets the length of the slider in a trackbar.

Parameters

iLength

Length, in pixels, of the slider.

Return Value

No return value.


TBM_SETTIC  (preliminaryWindows NT)
TBM_SETTIC  (preliminary−Windows NT)

TBM_SETTIC

wParam = 0;

lParam = (LPARAM) (LONG) lPosition;

The TBM_SETTIC message sets the position of a tick mark in a trackbar.

Parameters

lPosition

Position of the tick mark. This parameter must specify a positive value.

Return Value

Returns TRUE if the tick mark is set or FALSE otherwise.

Remarks

A trackbar creates its own first and last tick marks. An application should not use this message to set the first and last marks.


TBM_SETTICFREQ  (preliminaryWindows NT)
TBM_SETTICFREQ  (preliminary−Windows NT)

TBM_SETTICFREQ

wParam = (WPARAM) wFreq;

lParam = (LPARAM) (LONG) lPosition;

The TBM_SETTICFREQ message sets the interval frequency for tick marks in a trackbar. For example, if the frequency is set to two, a tick mark is displayed for every other increment in the trackbar's range. The default setting for the frequency is one; that is, every increment in the range is associated with a tick mark.

Parameters

wFreq

Frequency of the tick marks.

lPosition

Position of the tick mark. This parameter must specify a positive value.

Return Value

No return value.

Remarks

The trackbar must have the TBS_AUTOTICKS style to use this message.


TBN_BEGINADJUST  (preliminaryWindows NT)
TBN_BEGINADJUST  (preliminary−Windows NT)

TBN_BEGINADJUST

pnmhdr = (NMHDR FAR *) lParam;

The TBN_BEGINADJUST notification message notifies a toolbar's parent window that the user has begun customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

Parameters

pnmhdr

Pointer to an NMHDR structure that contains information about the notification message.

Return Value

No return value.

See Also

NMHDR, WM_NOTIFY


TBN_BEGINDRAG  (preliminaryWindows NT)
TBN_BEGINDRAG  (preliminary−Windows NT)

TBN_BEGINDRAG

ptbn = (TBNOTIFY FAR *) lParam;

The TBN_BEGINDRAG notification message notifies a toolbar's parent window that the user has begun dragging a button in a toolbar. This message is sent in the form of a WM_NOTIFY message.

Parameters

ptbn

Pointer to a TBNOTIFY structure. The iItem member contains the zero-based index of the button being dragged.

Return Value

No return value.

See Also

TBNOTIFY, WM_NOTIFY


TBN_CUSTHELP  (preliminaryWindows NT)
TBN_CUSTHELP  (preliminary−Windows NT)

TBN_CUSTHELP

pnmhdr = (NMHDR FAR *) lParam;

The TBN_CUSTHELP notification message notifies a toolbar's parent window that the user has chosen the Help button in the Customize Toolbar dialog box. This message is sent in the form of a WM_NOTIFY message.

Parameters

pnmhdr

Pointer to an NMHDR structure that contains information about the notification message.

Return Value

No return value.

See Also

NMHDR, WM_NOTIFY


TBN_ENDADJUST  (preliminaryWindows NT)
TBN_ENDADJUST  (preliminary−Windows NT)

TBN_ENDADJUST

pnmhdr = (NMHDR FAR *) lParam;

The TBN_ENDADJUST notification message notifies a toolbar's parent window that the user has stopped customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

Parameters

pnmhdr

Pointer to an NMHDR structure that contains information about the notification message.

Return Value

No return value.

See Also

NMHDR, WM_NOTIFY


TBN_ENDDRAG  (preliminaryWindows NT)
TBN_ENDDRAG  (preliminary−Windows NT)

TBN_ENDDRAG

ptbn = (TBNOTIFY FAR *) lParam;

The TBN_ENDDRAG notification message notifies the toolbar's parent window that the user has stopped dragging a button in a toolbar. This message is sent in the form of a WM_NOTIFY message.

Parameters

ptbn

Pointer to a TBNOTIFY structure. The iItem member contains the zero-based index of the button being dragged.

Return Value

No return value.

See Also

TBNOTIFY, WM_NOTIFY


TBN_GETBUTTONINFO  (preliminaryWindows NT)
TBN_GETBUTTONINFO  (preliminary−Windows NT)

TBN_GETBUTTONINFO

ptbn = (TBNOTIFY FAR *) lParam;

The TBN_GETBUTTONINFO notification message notifies the toolbar's parent window that the user is customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

Parameters

ptbn

Pointer to a TBNOTIFY structure. The iItem member specifies the zero-based index of a button. The pszText and cchText members specify the address and length, in characters, of the current button text. An application should fill the structure with information about the button.

Return Value

Returns TRUE if button information was copied to the specified structure or FALSE otherwise.

Remarks

The toolbar uses this notification message to retrieve information needed by the Customize Toolbar dialog box.

See Also

TBNOTIFY, WM_NOTIFY


TBN_QUERYDELETE  (preliminaryWindows NT)
TBN_QUERYDELETE  (preliminary−Windows NT)

TBN_QUERYDELETE

ptbn = (TBNOTIFY FAR *) lParam;

The TBN_QUERYDELETE notification message notifies the toolbar's parent window whether a button may be deleted from a toolbar while the user is customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

Parameters

ptbn

Pointer to a TBNOTIFY structure. The iItem member contains the zero-based index of the button to be deleted.

Return Value

Returns TRUE to allow the button to be deleted or FALSE to prevent the button from being deleted.

See Also

TBNOTIFY, WM_NOTIFY


TBN_QUERYINSERT  (preliminaryWindows NT)
TBN_QUERYINSERT  (preliminary−Windows NT)

TBN_QUERYINSERT

ptbn = (TBNOTIFY FAR *) lParam;

The TBN_QUERYINSERT notification message notifies the toolbar's parent window whether a button may be inserted to the left of the specified button while the user is customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

Parameters

ptbn

Pointer to a TBNOTIFY structure. The iItem member contains the zero-based index of the button to be inserted.

Return Value

Returns TRUE to allow a button to inserted in front of the given button or FALSE to prevent the button from being inserted.

See Also

TBNOTIFY, WM_NOTIFY


TBN_RESET  (preliminaryWindows NT)
TBN_RESET  (preliminary−Windows NT)

TBN_RESET

pnmhdr = (NMHDR FAR *) lParam;

The TBN_RESET notification message notifies the toolbar's parent window that the user has reset the content of the Customize Toolbar dialog box. This message is sent in the form of a WM_NOTIFY message.

Parameters

pnmhdr

Pointer to an NMHDR structure that contains information about the notification message.

Return Value

No return value.

See Also

NMHDR, WM_NOTIFY


TBN_TOOLBARCHANGE  (preliminaryWindows NT)
TBN_TOOLBARCHANGE  (preliminary−Windows NT)

TBN_TOOLBARCHANGE

pnmhdr = (NMHDR FAR *) lParam;

The TBN_TOOLBARCHANGE notification message notifies the toolbar's parent window that the user has customized a toolbar. This message is sent in the form of a WM_NOTIFY message.

Parameters

pnmhdr

Pointer to an NMHDR structure that contains information about the notification message.

Return Value

No return value.

See Also

NMHDR, WM_NOTIFY


TCM_ADJUSTRECT  (preliminaryWindows NT)
TCM_ADJUSTRECT  (preliminary−Windows NT)

TCM_ADJUSTRECT

wParam = (WPARAM) (BOOL) fLarger;  // operation to perform

lParam = (LPARAM) (LPRECT) prc;    // pointer to a RECT structure

// Corresponding macro

VOID TabCtrl_AdjustRect(HWND hwnd, BOOL fLarger, RECT FAR* prc);

The TCM_ADJUSTRECT message calculates a tab control's display area given a window rectangle or calculates the window rectangle that would correspond to a specified display area. You can send this message explicitly or by using the TabCtrl_AdjustRect macro.

Parameters

fLarger

Operation to perform. If this parameter is TRUE, prc specifies a display rectangle and receives the corresponding window rectangle. If this parameter is FALSE, prc specifies a window rectangle and receives the corresponding display area.

prc

Pointer to a RECT structure that specifies the given rectangle and receives the calculated rectangle.

hwnd

Handle to the tab control.

Return Value

No return value.

See Also

RECT


TCM_DELETEALLITEMS  (preliminaryWindows NT)
TCM_DELETEALLITEMS  (preliminary−Windows NT)

TCM_DELETEALLITEMS

wParam = 0;           // not used; must be zero

lParam = 0;           // not used; must be zero

// Corresponding macro

BOOL TabCtrl_DeleteAllItems(HWND hwnd);

The TCM_DELETEALLITEMS message removes all items from a tab control. You can send this message explicitly or by using the TabCtrl_DeleteAllItems macro.

Parameters

hwnd

Handle to the tab control.

Return Value

Returns TRUE if successful or FALSE otherwise.


TCM_DELETEITEM  (preliminaryWindows NT)
TCM_DELETEITEM  (preliminary−Windows NT)

TCM_DELETEITEM

wParam = (WPARAM) (int) iItem;  // index of the item to delete

lParam = 0;                     // not used; must be zero

// Corresponding macro

BOOL TabCtrl_DeleteItem(HWND hwnd, int iItem);

The TCM_DELETEITEM message removes an item from a tab control. You can send this message explicitly or by using the TabCtrl_DeleteItem macro.

Parameters

iItem

Index of the item to delete.

hwnd

Handle to the tab control.

Return Value

Returns TRUE if successful or FALSE otherwise.


TCM_GETBKCOLOR  (preliminaryWindows NT)
TCM_GETBKCOLOR  (preliminary−Windows NT)

TCM_GETBKCOLOR

wParam = 0;  // not used; must be zero

lParam = 0;  // not used; must be zero

// Corresponding macro

(COLORREF) TabCtrl_GetBkColor(HWND hwnd);

The TCM_GETBKCOLOR message retrieves the current background color for a tab control. You can send this message explicitly or by using the TabCtrl_GetBkColor macro.

Parameters

hwnd

Handle to the tab control.

Return Value

Returns a COLORREF value that specifies the tab control's current text color.

See Also

COLORREF


TCM_GETCURFOCUS  (preliminaryWindows NT)
TCM_GETCURFOCUS  (preliminary−Windows NT)

TCM_GETCURFOCUS

wParam = 0;  // not used; must be zero

lParam = 0;  // not used; must be zero

// Corresponding macro

int TabCtrl_GetCurFocus(HWND hwnd);

The TCM_GETCURFOCUS message returns the index of the item that has the focus in a tab control. You can send this message explicitly or by using the TabCtrl_GetCurFocus macro.

Parameters

hwnd

Handle to the tab control.

Return Value

Returns the index of the tab item that has the focus

Remarks

The item that has the focus may be different than the selected item.


TCM_GETCURSEL  (preliminaryWindows NT)
TCM_GETCURSEL  (preliminary−Windows NT)

TCM_GETCURSEL

wParam = 0;   // not used; must be zero

lParam = 0;   // not used; must be zero

// Corresponding macro

int TabCtrl_GetCurSel(HWND hwnd);

The TCM_GETCURSEL message determines the currently selected tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetCurSel macro.

Parameters

hwnd

Handle to the tab control.

Return Value

Returns the index of the selected tab if successful or  − 1 if no tab is selected.


TCM_GETIMAGELIST  (preliminaryWindows NT)
TCM_GETIMAGELIST  (preliminary−Windows NT)

TCM_GETIMAGELIST

wParam = 0;   // not used; must be zero

lParam = 0;   // not used; must be zero

// Corresponding macro

HIMAGELIST TabCtrl_GetImageList(HWND hwnd);

The TCM_GETIMAGELIST message retrieves the image list associated with a tab control. You can send this message explicitly or by using the TabCtrl_GetImageList macro.

Return Value

Returns the handle to the image list if successful or NULL otherwise.


TCM_GETITEM  (preliminaryWindows NT)
TCM_GETITEM  (preliminary−Windows NT)

TCM_GETITEM

wParam = (WPARAM) (int) iItem;

lParam = (LPARAM) (TC_ITEM FAR *) pitem;

// Corresponding macro

BOOL TabCtrl_GetItem(HWND hwnd, int iItem, TC_ITEM FAR* pitem);

The TCM_GETITEM message retrieves information about a tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetItem macro.

Parameters

iItem

Index of the tab.

pitem

Pointer to a TC_ITEM structure that specifies the information to retrieve and receives information about the tab. When the message is sent, the mask member specifies which attributes to return.

If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

hwnd

Handle to the tab control.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

TC_ITEM


TCM_GETITEMCOUNT  (preliminaryWindows NT)
TCM_GETITEMCOUNT  (preliminary−Windows NT)

TCM_GETITEMCOUNT

wParam = 0;   // not used; must be zero

lParam = 0;   // not used; must be zero

// Corresponding macro

int TabCtrl_GetItemCount(HWND hwnd);

The TCM_GETITEMCOUNT message retrieves the number of tabs in the tab control. You can send this message explicitly or by using the TabCtrl_GetItemCount macro.

Parameters

hwnd

Handle to the tab control.

Return Value

Returns the number of items if successful or zero otherwise.


TCM_GETITEMRECT  (preliminaryWindows NT)
TCM_GETITEMRECT  (preliminary−Windows NT)

TCM_GETITEMRECT

wParam = (WPARAM) (int) iItem;       // index of the tab

lParam = (LPARAM) (RECT FAR *) prc;  // pointer to a structure to receive rectangle of tab

// Corresponding macro

BOOL TabCtrl_GetItemRect(HWND hwnd, int iItem, RECT FAR* prc);

The TCM_GETITEMRECT message retrieves the bounding rectangle for a tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetItemRect macro.

Parameters

iItem

Index of the tab.

prc

Pointer to a RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.

hwnd

Handle to the tab control.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

RECT


TCM_GETROWCOUNT  (preliminaryWindows NT)
TCM_GETROWCOUNT  (preliminary−Windows NT)

TCM_GETROWCOUNT

wParam = 0;   // not used; must be zero

lParam = 0;   // not used; must be zero

// Corresponding macro

int TabCtrl_GetRowCount(HWND hwnd);

The TCM_GETROWCOUNT message retrieves the current number of rows of tabs in a tab control. You can send this message explicitly or by using the TabCtrl_GetRowCount macro.

Parameters

hwnd

Handle to the tab control.

Return Value

Returns the number of rows of tabs.

Remarks

Only tab controls that have the TCS_MULTILINE style can have multiple rows of tabs.


TCM_GETTOOLTIPS  (preliminaryWindows NT)
TCM_GETTOOLTIPS  (preliminary−Windows NT)

TCM_GETTOOLTIPS

wParam = 0;   // not used; must be zero

lParam = 0;   // not used; must be zero

// Corresponding macro

int TabCtrl_GetToolTips(HWND hwnd);

The TCM_GETTOOLTIPS message retrieves the handle to the tooltip control associated with a tab control. You can send this message explicitly or by using the TabCtrl_GetToolTips macro.

Parameters

hwnd

Handle to the tab control.

Return Value

Returns the handle to the tooltip control if successful or NULL otherwise.

Remarks

A tab control creates a tooltip control if it has the TCS_TOOLTIPS style. You can also assign a tooltip control to a tab control by using the TCM_SETTOOLTIPS message.

See Also

TCM_SETTOOLTIPS


TCM_HITTEST  (preliminaryWindows NT)
TCM_HITTEST  (preliminary−Windows NT)

TCM_HITTEST

wParam = 0;    // not used; must be zero

lParam = (LPARAM) (TC_HITTESTINFO FAR *) pinfo; \\pointer to struct specifying position to test

// Corresponding macro

int TabCtrl_HitTest(HWND hwnd, TC_HITTESTINFO FAR* pinfo);

The TCM_HITTEST message determines which tab, if any, is at a specified screen position. You can send this message explicitly or by using the TabCtrl_HitTest macro.

Parameters

pinfo

Pointer to a TC_HITTESTINFO structure that specifies the screen position to test.

hwnd

Handle to the tab control.

Return Value

Returns the index of the tab or  − 1 if no tab is at the specified position.

See Also

TC_HITTESTINFO


TCM_INSERTITEM  (preliminaryWindows NT)
TCM_INSERTITEM  (preliminary−Windows NT)

TCM_INSERTITEM

wParam = (WPARAM) (int) iItem;                 \\index of the new tab

lParam = (LPARAM) (const TC_ITEM FAR*) pitem;  \\pointer to struct specifying tab attributes

// Corresponding macro

int TabCtrl_InsertItem(HWND hwnd, int iItem,

        const TC_ITEM FAR* pitem);

The TCM_INSERTITEM message inserts a new tab in a tab control. You can send this message explicitly or by using the TabCtrl_InsertItem macro.

Parameters

iItem

Index of the new tab.

pitem

Pointer to a TC_ITEM structure that specifies the attributes of the tab.

hwnd

Handle to the tab control.

Return Value

Returns the index of the new tab if successful or  − 1 otherwise.

See Also

TC_ITEM


TCM_REMOVEIMAGE  (preliminaryWindows NT)
TCM_REMOVEIMAGE  (preliminary−Windows NT)

TCM_REMOVEIMAGE

wParam = (WPARAM) (int) iImage;  // index of the image to remove

lParam = 0;                      // not used; must be zero

// Corresponding macro

void TabCtrl_RemoveImage(HWND hwnd, int iImage);

The TCM_REMOVEIMAGE message removes an image from a tab control's image list. You can send this message explicitly or by using the TabCtrl_RemoveImage macro.

Parameters

iImage

Index of the image to remove.

hwnd

Handle to the tab control.

Return Value

No return value.

Remarks

The tab control updates each tab's image index, so each tab remains associated with the same image it had been.


TCM_SETBKCOLOR  (preliminaryWindows NT)
TCM_SETBKCOLOR  (preliminary−Windows NT)

TCM_SETBKCOLOR

wParam = 0;                          // not used; must be zero

lParam = (LPARAM) (COLORREF) clrBk;  // value specifying background color

// Corresponding macro

BOOL TabCtrl_SetBkColor(HWND hwnd, COLORREF clrBk);

The TCM_SETBKCOLOR message sets the background color for a tab control, overriding the default window background color. You can send this message explicitly or by using the TabCtrl_SetBkColor macro.

Parameters

clrBk

COLORREF value that specifies the new background color.

hwnd

Handle to the tab control.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

COLORREF


TCM_SETCURSEL  (preliminaryWindows NT)
TCM_SETCURSEL  (preliminary−Windows NT)

TCM_SETCURSEL

wParam = (WPARAM) (int) iItem;  // index of the tab to select

lParam = 0;                     // not used; must be zero

// Corresponding macro

int TabCtrl_SetCurSel(HWND hwnd, int iItem);

The TCM_SETCURSEL message selects a tab in a tab control. You can send this message explicitly or by using the TabCtrl_SetCurSel macro.

Parameters

iItem

Index of the tab to select.

hwnd

Handle to the tab control.

Return Value

Returns the index of the previously selected tab if successful or  − 1 otherwise.

Remarks

A tab control does not send a TCN_SELCHANGING or TCN_SELCHANGE notification message when a tab is selected using this message.

See Also

TCN_SELCHANGE, TCN_SELCHANGING


TCM_SETIMAGELIST  (preliminaryWindows NT)
TCM_SETIMAGELIST  (preliminary−Windows NT)

TCM_SETIMAGELIST

wParam = 0;                           // not used; must be zero

lParam = (LPARAM) (HIMAGELIST) himl;  // handle of image list to assign to tab control

// Corresponding macro

BOOL TabCtrl_SetImageList(HWND hwnd, HIMAGELIST himl);

The TCM_SETIMAGELIST message assigns an image list to a tab control. You can send this message explicitly or by using the TabCtrl_SetImageList macro.

Parameters

himl

Handle of the image list to assign to the tab control.

hwnd

Handle to the tab control.

Return Value

Returns the handle to the previous image list or NULL if there is no previous image list.


TCM_SETITEM  (preliminaryWindows NT)
TCM_SETITEM  (preliminary−Windows NT)

TCM_SETITEM

wParam = (WPARAM) (int) iItem;            // index of the item

lParam = (LPARAM) (TC_ITEM FAR *) pitem;  // pointer to struct containing item attributes

// Corresponding macro

BOOL TabCtrl_SetItem(HWND hwnd, int iItem, TC_ITEM FAR* pitem);

The TCM_SETITEM message sets some or all of a tab's attributes. You can send this message explicitly or by using the TabCtrl_SetItem macro.

Parameters

iItem

Index of the item.

pitem

Pointer to a TC_ITEM structure that contains the new item attributes. The mask member specifies which attributes to set.

If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

hwnd

Handle to the tab control.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

TC_ITEM


TCM_SETITEMEXTRA  (preliminaryWindows NT)
TCM_SETITEMEXTRA  (preliminary−Windows NT)

TCM_SETITEMEXTRA

wParam = (WPARAM) (int) cb;  // number of extra bytes

lParam = 0;                  // not used; must be zero

// Corresponding macro

BOOL TabCtrl_SetItemExtra(HWND hwnd, int cb);

The TCM_SETITEMEXTRA message sets the number of bytes per tab reserved for application-defined data in a tab control. You can send this message explicitly or by using the TabCtrl_SetItemExtra macro.

Parameters

cb

Number of extra bytes.

hwnd

Handle to the tab control.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

By default, the number of extra bytes is four. An application that changes the number of extra bytes cannot use the TC_ITEM structure to retrieve and set the application-defined data for a tab. Instead, you must define a new structure that consists of the TC_ITEMHEADER structure followed by application-defined members.

An application should only change the number of extra bytes when a tab control does not contain any tabs.

See Also

TC_ITEM, TC_ITEMHEADER


TCM_SETITEMSIZE  (preliminaryWindows NT)
TCM_SETITEMSIZE  (preliminary−Windows NT)

TCM_SETITEMSIZE

wParam = 0;                   // not used; must be zero

lParam = MAKELPARAM(cx, cy);  // new width and height, in pixels

// Corresponding macro

DWORD TabCtrl_SetItemSize(HWND hwnd, int cx, int cy);

The TCM_SETITEMSIZE message sets the width and height of tabs in a fixed-width or owner-drawn tab control. You can send this message explicitly or by using the TabCtrl_SetItemSize macro.

Parameters

cx and cy

New width and height, in pixels.

hwnd

Handle to the tab control.

Return Value

Returns the old width and height. The width is in the low-order word of the return value, and the height is in the high-order word.


TCM_SETPADDING  (preliminaryWindows NT)
TCM_SETPADDING  (preliminary−Windows NT)

TCM_SETPADDING

wParam = 0;                   // not used; must be zero

lParam = MAKELPARAM(cx, cy);  // amount of horizontal and vertical padding, in pixels

// Corresponding macro

void TabCtrl_SetPadding(HWND hwnd, int cx, int cy);

The TCM_SETPADDING message sets the amount of space (padding) around each tab's icon and label in a tab control. You can send this message explicitly or by using the TabCtrl_SetPadding macro.

Parameters

cx and cy

Amount of horizontal and vertical padding, in pixels.

hwnd

Handle to the tab control.

Return Value

No return value.


TCM_SETTOOLTIPS  (preliminaryWindows NT)
TCM_SETTOOLTIPS  (preliminary−Windows NT)

TCM_SETTOOLTIPS

wParam = (WPARAM) (HWND) hwndTT;    \\handle to the tooltip control

lParam = 0;                       // not used; must be zero

// Corresponding macro

void TabCtrl_SetToolTips(HWND hwndTab, HWND hwndTT);

The TCM_SETTOOLTIPS message assigns a tooltip control to a tab control. You can send this message explicitly or by using the TabCtrl_SetToolTips macro.

Parameters

hwndTT

Handle to the tooltip control.

hwndTab

Handle to the tab control.

Return Value

No return value.

Remarks

You can get the tooltip control associated with a tab control by using the TCM_GETTOOLTIPS message.

See Also

TCM_GETTOOLTIPS


TCN_KEYDOWN  (preliminaryWindows NT)
TCN_KEYDOWN  (preliminary−Windows NT)

TCN_KEYDOWN

pnm = (TC_KEYDOWN FAR *) lParam;

The TCN_KEYDOWN notification message notifies a tab control's parent window that a key has been pressed. This message is sent in the form of a WM_NOTIFY message.

Parameters

pnm

Pointer to a TC_KEYDOWN structure.

Return Value

No return value.

See Also

TC_KEYDOWN, WM_NOTIFY


TCN_SELCHANGE  (preliminaryWindows NT)
TCN_SELCHANGE  (preliminary−Windows NT)

TCN_SELCHANGE

idTabCtl = (int) LOWORD(wParam);

hwndTabCtl = (HWND) lParam;

The TCN_SELCHANGE notification message notifies a tab control's parent window that the currently selected tab has changed. This message is sent in the form of a WM_NOTIFY message.

Return Value

No return value.

Remarks

To determine the currently selected tab, use the TabCtrl_GetCurSel macro.

See Also

WM_NOTIFY


TCN_SELCHANGING  (preliminaryWindows NT)
TCN_SELCHANGING  (preliminary−Windows NT)

TCN_SELCHANGE

idTabCtl = (int) LOWORD(wParam);

hwndTabCtl = (HWND) lParam;

The TCN_SELCHANGING notification message notifies a tab control's parent window that the currently selected tab is about to change. This message is sent in the form of a WM_NOTIFY message.

Return Value

Returns TRUE to prevent the selection from changing or FALSE to allow the selection to change.

Remarks

To determine the currently selected tab, use the TabCtrl_GetCurSel macro.

See Also

WM_NOTIFY


TTM_ACTIVATE  (preliminaryWindows NT)
TTM_ACTIVATE  (preliminary−Windows NT)

TTM_ACTIVATE

wParam = (WPARAM) (BOOL) fActivate;

lParam = 0;

The TTM_ACTIVATE message activates or deactivates a tooltip control.

Parameters

fActivate

Activation flag. If this parameter is TRUE, the tooltip control is activated. If it is FALSE, the tooltip control is deactivated.

Return Value

No return value.


TTM_ADDTOOL  (preliminaryWindows NT)
TTM_ADDTOOL  (preliminary−Windows NT)

TTM_ADDTOOL

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

The TTM_ADDTOOL message registers a tool with a tooltip control.

Parameters

lpti

Pointer to a TOOLINFO structure containing information that the tooltip control needs to display text for the tool.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

TOOLINFO


TTM_DELTOOL  (preliminaryWindows NT)
TTM_DELTOOL  (preliminary−Windows NT)

TTM_DELTOOL

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

The TTM_DELTOOL message removes a tool from a tooltip control.

Parameters

lpti

Pointer to a TOOLINFO structure. The hwnd and uId members identify the tool to remove, and the cbSize member must specify the size of the structure. All other members are ignored.

Return Value

No return value.

See Also

TOOLINFO


TTM_ENUMTOOLS  (preliminaryWindows NT)
TTM_ENUMTOOLS  (preliminary−Windows NT)

TTM_ENUMTOOLS

wParam = (WPARAM) (UINT) iTool;

lParam = (LPARAM) (LPTOOLINFO) lpti;

The TTM_ENUMTOOLS message retrieves the information that a tooltip control maintains about the current tool; that is, the tool for which the tooltip is currently displaying text.

Parameters

iTool

Zero-based index of the tool for which to retrieve information.

lpti

Pointer to a TOOLINFO structure that receives information about the tool. Before sending this message, the cbSize member must specify the size of the structure.

Return Value

Returns TRUE if any tools are enumerated or FALSE otherwise.

Remarks

Retrieves the information that a tooltip control maintains about a tool.

See Also

TOOLINFO


TTM_GETCURRENTTOOL  (preliminaryWindows NT)
TTM_GETCURRENTTOOL  (preliminary−Windows NT)

TTM_GETCURRENTTOOL

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

The TTM_GETCURRENTTOOL message retrieves the text that a tooltip control maintains for a tool.

Parameters

lpti

Pointer to a TOOLINFO structure that receives information about the current tool.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

TOOLINFO


TTM_GETTEXT  (preliminaryWindows NT)
TTM_GETTEXT  (preliminary−Windows NT)

TTM_GETTEXT

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

The TTM_GETTEXT message retrieves a count of the tools maintained by a tooltip control.

Parameters

lpti

Pointer to a TOOLINFO structure. When sending the message, the hwnd and uId members identify a tool. If the tooltip control includes the tool, the lpszText member receives the pointer to the string.

Return Value

No return value.

See Also

TOOLINFO


TTM_GETTOOLCOUNT  (preliminaryWindows NT)
TTM_GETTOOLCOUNT  (preliminary−Windows NT)

TTM_GETTOOLCOUNT

wParam = 0;

lParam = 0;

The TTM_GETTOOLCOUNT message retrieves the information that a tooltip control maintains about a tool.

Return Value

Returns a count of tools.


TTM_GETTOOLINFO  (preliminaryWindows NT)
TTM_GETTOOLINFO  (preliminary−Windows NT)

TTM_GETTOOLINFO

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

The TTM_GETTOOLINFO message retrieves the information that a tooltip control maintains about a tool.

Parameters

lpti

Pointer to a TOOLINFO structure. When sending the message, the hwnd and uId members identify a tool, and the cbSize member must specify the size of the structure. If the tooltip control includes the tool, the structure receives information about the tool.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

TOOLINFO


TTM_HITTEST  (preliminaryWindows NT)
TTM_HITTEST  (preliminary−Windows NT)

TTM_HITTEST

wParam = 0;

lParam = (LPARAM) (LPHITTESTINFO) lphti;

The TTM_HITTEST message tests a point to determine whether it is within the bounding rectangle of the specified tool and, if the point is within, retrieves information about the tool.

Parameters

lphti

Pointer to a TTHITTESTINFO structure. When sending the message, the hwnd member must specify the handle of a tool and the pt member must specify the coordinates of a point. If the return value is TRUE, the ti member receives information about the tool that occupies the point.

Return Value

Returns TRUE if the tool occupies the specified point or FALSE otherwise.

See Also

TTHITTESTINFO


TTM_NEWTOOLRECT  (preliminaryWindows NT)
TTM_NEWTOOLRECT  (preliminary−Windows NT)

TTM_NEWTOOLRECT

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

The TTM_NEWTOOLRECT message sets a new bounding rectangle for a tool.

Parameters

lpti

Pointer to a TOOLINFO structure. The hwnd and uId members identify a tool, and the rect member specifies the new bounding rectangle.

Return Value

No return value.

See Also

TOOLINFO


TTM_RELAYEVENT  (preliminaryWindows NT)
TTM_RELAYEVENT  (preliminary−Windows NT)

TTM_RELAYEVENT

wParam = 0;

lParam = (LPARAM) (LPMSG) lpmsg;

The TTM_RELAYEVENT message passes a mouse message to a tooltip control for processing.

Parameters

lpmsg

Pointer to an MSG structure that contains the message to relay.

Return Value

No return value.

Remarks

A tooltip control processes only the following messages passed to it by the TTM_RELAYEVENT message.

WM_LBUTTONDOWN	WM_MOUSEMOVE
WM_LBUTTONUP	WM_RBUTTONDOWN
WM_MBUTTONDOWN	WM_RBUTTONUP
WM_MBUTTONUP
All other messages are ignored.

See Also

MSG


TTM_SETDELAYTIME  (preliminaryWindows NT)
TTM_SETDELAYTIME  (preliminary−Windows NT)

TTM_SETDELAYTIME

wParam = (WPARAM) uFlag;

lParam = (LPARAM) (int) iDelay;

The TTM_SETDELAYTIME message sets the initial, reshow, and autopopup durations for a tooltip control.

Parameters

uFlag

Duration to set. This parameter can be one of the following values:

Value	Meaning
TTDT_AUTOMATIC	Automatically calculates the initial, reshow, and autopopup durations based on the value of iDelay.
TTDT_AUTOPOPUP	Sets the length of time before the tooltip window is hidden if the cursor remains stationary in the tool's bounding rectangle after the tooltip window has appeared.
TTDT_INITIAL	Sets the length of time that the cursor must remain stationary within the bounding rectangle of a tool before the tooltip window is displayed.
TTDT_RESHOW	Sets the length of the delay before subsequent tooltip windows are displayed when the cursor is moved from one tool to another.
iDelay

New duration, in milliseconds.

Return Value

No return value.


TTM_SETTOOLINFO  (preliminaryWindows NT)
TTM_SETTOOLINFO  (preliminary−Windows NT)

TTM_SETTOOLINFO

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

The TTM_SETTOOLINFO message sets the information that a tooltip control maintains for a tool.

Parameters

lpti

Pointer to a TOOLINFO structure that specifies the information to set.

Return Value

No return value.

See Also

TOOLINFO


TTM_UPDATETIPTEXT

TTM_UPDATETIPTEXT

wParam = 0;

lParam = (LPARAM) (LPTOOLINFO) lpti;

The TTM_UPDATETIPTEXT message sets the tooltip text for a tool.

Parameters

lpti

Pointer to a TOOLINFO structure. The hinst and lpszText members must specify the instance handle and the pointer to the text. The hwnd and uId members identify the tool to update.

Return Value

No return value.

See Also

TOOLINFO


TTM_WINDOWFROMPOINT

TTM_WINDOWFROMPOINT

wParam = 0;

lParam = (POINT FAR *) lppt;

The TTM_WINDOWFROMPOINT message allows a subclass procedure to cause a tooltip to display text for a window other than the one beneath the mouse cursor.

Parameters

lppt

Pointer to a POINT structure that defines the point to be checked.

Return Value

The return value is the handle to the window that contains the point, or NULL if no window exists at the specified point.

Remarks

This message is intended to be processed by an application that subclasses a tooltip. It is not intended to be sent by an application. A tooltip sends this message to itself before displaying the text for a window. By changing the coordinates of the point specified by lppt, the subclass procedure can cause the tooltip to display text for a window other than the one beneath the mouse cursor.

See Also

POINT


TTN_NEEDTEXT  (preliminaryWindows NT)
TTN_NEEDTEXT  (preliminary−Windows NT)

TTN_NEEDTEXT

idTT = (int) wParam;

lpttt = (LPTOOLTIPTEXT) lParam;

The TTN_NEEDTEXT notification message retrieves text for a tool. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

idTT

Identifier of the tooltip control.

lpttt

Pointer to a TOOLTIPTEXT structure. The hdr member identifies the tool for which text is needed. The receiving window can specify the string by taking one of the following actions:

•	Copying the text to the buffer specified by the szText member.

•	Copying the address of the buffer that contains the text to the lpszText member.

•	Copying the identifier of a string resource to the lpszText member and copying the handle of the instance that contains the resource to the hinst member.

Return Value

No return value.

Remarks

This notification message is sent to the window specified in the hwnd member of the TOOLINFO structure for the tool. This notification is sent only if the LPSTR_TEXTCALLBACK value is specified when the tool is added to a tooltip control.

When a TTN_NEEDTEXT notification is received, the application can set or clear the TTF_RTLREADING value in the uFlags member of the TOOLTIPTEXT structure pointed to by lpttt as required. This is the only flag that can be changed during the notification callback.

See Also

TOOLINFO, TOOLTIPTEXT, WM_NOTIFY


TTN_POP  (preliminaryWindows NT)
TTN_POP  (preliminary−Windows NT)

TTN_POP

idTT = (int) wParam;

pnmh = (NMHDR FAR *) lParam;

The TTN_POP notification message notifies the owner window that a tooltip is about to be hidden. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

idTT

Identifier of the tooltip control.

lpttt

Return Value

No return value.

Remarks

Address of an NMHDR structure.

See Also

NMHDR, WM_NOTIFY


TTN_SHOW  (preliminaryWindows NT)
TTN_SHOW  (preliminary−Windows NT)

TTN_SHOW

idTT = (int) wParam;

pnmh = (NMHDR FAR *) lParam;

The TTN_SHOW notification message notifies the owner window that a tooltip is about to be displayed. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

idTT

Identifier of the tooltip control.

lpttt

Return Value

No return value.

Remarks

Address of an NMHDR structure.

See Also

NMHDR, WM_NOTIFY


TVM_CREATEDRAGIMAGE  (preliminaryWindows NT)
TVM_CREATEDRAGIMAGE  (preliminary−Windows NT)

TVM_CREATEDRAGIMAGE

wParam = 0;

lParam = (LPARAM) (HTREEITEM) hitem;

// Corresponding macro

HIMAGELIST TreeView_CreateDragImage(hwnd, hitem);

The TVM_CREATEDRAGIMAGE message creates a dragging bitmap for the specified item in a tree-view control, creates an image list for the bitmap, and adds the bitmap to the image list. An application can display the image when dragging the item by using the image list functions. You can send this message explicitly or by using the TreeView_CreateDragImage macro.

Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the item that receives the new dragging bitmap.

Return Value

Returns the handle of the image list to which the dragging bitmap was added if successful or NULL otherwise.


TVM_DELETEITEM  (preliminaryWindows NT)
TVM_DELETEITEM  (preliminary−Windows NT)

TVM_DELETEITEM

wParam = 0;

lParam = (LPARAM) (HTREEITEM) hitem;

// Corresponding macro

BOOL TreeView_DeleteItem(hwnd, hitem);

// Related macro

BOOL TreeView_DeleteAllItems(hwnd);

The TVM_DELETEITEM message removes an item from a tree-view control. You can send this message explicitly or by using the TreeView_DeleteItem or TreeView_DeleteAllItems macro.

Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the item to delete. If hitem is the TVI_ROOT value, all items are deleted from the tree-view control.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message. The parent window receives a TVN_DELETEITEM notification message when the item is removed.

See Also

TVN_DELETEITEM, TVN_ENDLABELEDIT


TVM_EDITLABEL  (preliminaryWindows NT)
TVM_EDITLABEL  (preliminary−Windows NT)

TVM_EDITLABEL

wParam = 0;

lParam = (LPARAM) (HTREEITEM) hitem;

// Corresponding macro

HWND TreeView_EditLabel(hwnd, hitem);

The TVM_EDITLABEL message begins in-place editing of the specified item's text, replacing the text of the item with a single-line edit control containing the text. This message implicitly selects and focuses the specified item. You can send this message explicitly or by using the TreeView_EditLabel macro.

Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the item to edit.

Return Value

Returns the handle to the edit control used to edit the item text if successful or NULL otherwise.

Remarks

This message sends a TVN_BEGINLABELEDIT notification message to the parent of the tree-view control.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but do not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See Also

TVN_BEGINLABELEDIT, SetFocus


TVM_ENDEDITLABELNOW  (preliminaryWindows NT)
TVM_ENDEDITLABELNOW  (preliminary−Windows NT)

TVM_ENDEDITLABELNOW

wParam = (WPARAM) (BOOL) fCancel;

lParam = 0;

// Corresponding macro

BOOL TreeView_EndEditLabelNow(hwnd, fCancel);

The TVM_ENDEDITLABELNOW message ends the editing of a tree-view item's label.

Parameters

hwnd

Handle to the tree-view control.

fCancel

Variable that indicates whether the editing is canceled without being saved to the label. If this parameter is TRUE, the system cancels editing without saving the changes. Otherwise, the system saves the changes to the label.

Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

This message causes the TVN_ENDLABELEDIT notification message to be sent to the parent window of the tree-view control.

See Also

TVN_ENDLABELEDIT


TVM_ENSUREVISIBLE  (preliminaryWindows NT)
TVM_ENSUREVISIBLE  (preliminary−Windows NT)

TVM_ENSUREVISIBLE

wParam = 0;

lParam = (LPARAM) (HTREEITEM) hitem;

// Corresponding macro

BOOL TreeView_EnsureVisible(hwnd, hitem);

The TVM_ENSUREVISIBLE message ensures that a tree-view item is visible, expanding the parent item or scrolling the tree-view control, if necessary. You can send this message explicitly or by using the TreeView_EnsureVisible macro.

Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the item.

Return Value

Returns TRUE if the system scrolled the items in the tree view control to ensure that the specified item is visible. Otherwise the message returns FALSE.

Remarks

If the message expands the parent item, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

See Also

TVN_ITEMEXPANDED, TVN_ITEMEXPANDING


TVM_EXPAND  (preliminaryWindows NT)
TVM_EXPAND  (preliminary−Windows NT)

TVM_EXPAND

wParam = (WPARAM) (UINT) flag;

lParam = (LPARAM) (HTREEITEM) hitem;

// Corresponding macro

BOOL TreeView_Expand(hwnd, hitem, flag);

The TVM_EXPAND message expands or collapses the list of child items, if any, associated with the specified parent item. You can send this message explicitly or by using the TreeView_Expand macro.

Parameters

hwnd

Handle to the tree-view control.

hitem

Handle to the parent item to expand or collapse.

flag

Action flag. This parameter can be one of the following values:

Value	Meaning
TVE_COLLAPSE	Collapses the list.
TVE_COLLAPSERESET	Collapses the list and removes the child items. Note that TVE_COLLAPSE must also be specified.
TVE_EXPAND	Expands the list.
TVE_TOGGLE	Collapses the list if it is currently expanded or expands it if it is currently collapsed.
Return Value

Returns TRUE if any change took place or FALSE otherwise.

Remarks

This message does not send the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages to the parent window.

See Also

TVN_ITEMEXPANDED, TVN_ITEMEXPANDING


TVM_GETCOUNT  (preliminaryWindows NT)
TVM_GETCOUNT  (preliminary−Windows NT)

TVM_GETCOUNT

wParam = 0;

lParam = 0;

// Corresponding macro

UINT TreeView_GetCount(hwnd);

The TVM_GETCOUNT message retrieves a count of the items in a tree-view control. You can send this message explicitly or by using the TreeView_GetCount macro.

Parameters

hwnd

Handle to the tree-view control.

Return Value

Returns the count of items.


TVM_GETEDITCONTROL  (preliminaryWindows NT)
TVM_GETEDITCONTROL  (preliminary−Windows NT)

TVM_GETEDITCONTROL

wParam = 0;

lParam = 0;

// Corresponding macro

HWND TreeView_GetEditControl(hwnd);

The TVM_GETEDITCONTROL message retrieves the handle to the edit control being used to edit a tree-view item's text. You can send this message explicitly or by using the TreeView_GetEditControl macro.

Parameters

hwnd

Handle to the tree-view control.

Return Value

Returns the handle to the edit control if successful or NULL otherwise.


TVM_GETIMAGELIST  (preliminaryWindows NT)
TVM_GETIMAGELIST  (preliminary−Windows NT)

TVM_GETIMAGELIST

wParam = (WPARAM) iImage;

lParam = 0;

// Corresponding macro

HIMAGELIST TreeView_GetImageList(hwnd, iImage);

The TVM_GETIMAGELIST message retrieves the handle to the normal or state image list associated with a tree-view control. You can send this message explicitly or by using the TreeView_GetImageList macro.

Parameters

hwnd

Handle to the image list.

iImage

Type of image list to retrieve. This parameter can be one of the following values:

Value	Meaning
TVSIL_NORMAL	Retrieves the normal image list, which contains the selected and unselected images for the tree-view item.
TVSIL_STATE	Retrieves the state image list, which contains the images for tree-view items that are in a user-defined state.
Return Value

Returns the handle to the image list.


TVM_GETINDENT  (preliminaryWindows NT)
TVM_GETINDENT  (preliminary−Windows NT)

TV_GETINDENT

wParam = 0;

lParam = 0;

// Corresponding macro

UINT TreeView_GetIndent(hwnd);

The TVM_GETINDENT message retrieves the amount, in pixels, that child items are indented relative to their parent items. You can send this message explicitly or by using the TreeView_GetIndent macro.

Parameters

hwnd

Handle to the tree-view control.

Return Value

Returns the amount of indentation.


TVM_GETISEARCHSTRING  (preliminaryWindows NT)
TVM_GETISEARCHSTRING  (preliminary−Windows NT)

TVM_GETISEARCHSTRING

wParam = 0;

lParam = (LPARAM) (LPSTR) lpsz;

// Corresponding macro

BOOL TreeView_GetISearchString(hwnd, lpsz);

The TVM_GETISEARCHSTRING message retrieves the incremental search string for a tree-view control. The tree-view control uses the incremental search string to select an item based on characters typed by the user.

Parameters

hwnd

Handle to the tree-view control.

lpsz

Pointer to the buffer that receives the incremental search string.

Return Value

Returns the number of characters in the incremental search string.

If the tree-view control is not in incremental search mode, the return value is zero.


TVM_GETITEM  (preliminaryWindows NT)
TVM_GETITEM  (preliminary−Windows NT)

TVM_GETITEM

wParam = 0;

lParam = (LPARAM) (TV_ITEM FAR*) pitem;

// Corresponding macro

BOOL TreeView_GetItem(hwnd, pitem);

The TVM_GETITEM message retrieves some or all of a tree-view item's attributes. You can send this message explicitly or by using the TreeView_GetItem macro.

Parameters

hwnd

Handle to the tree-view control.

pitem

Pointer to a TV_ITEM structure that specifies the information to retrieve and receives information about the item. When the message is sent, the hItem member identifies the item to retrieve information about and the mask member specifies the attributes to retrieve.

If mask specifies the TVIF_TEXT value, the pszText member must contain the pointer to the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

If mask specifies the TVIF_STATE value, the stateMask member indicates which item states are to be returned.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

TV_ITEM


TVM_GETITEMRECT  (preliminaryWindows NT)
TVM_GETITEMRECT  (preliminary−Windows NT)

TVM_GETITEMRECT

wParam = (WPARAM) (BOOL) fItemRect;

lParam = (LPARAM) (RECT FAR*) prc;

// Corresponding macro

BOOL TreeView_GetItemRect(hwnd, hitem, prc, fItemRect);

The TVM_GETITEMRECT message retrieves the bounding rectangle for a tree-view item and indicates whether the item is visible. You can send this message explicitly or by using the TreeView_GetItemRect macro.

Parameters

hwnd and hitem

Handle to the tree-view control, and the handle to the item.

prc

Pointer to a RECT structure that receives the bounding rectangle. The coordinates are relative to the upper-left corner of the tree-view control.

fItemRect

Value specifying the portion of the item for which to retrieve the bounding rectangle. If this parameter is TRUE, the bounding rectangle includes only the text of the item. Otherwise, it includes the entire line that the item occupies in the tree-view control.

Return Value

If the item is visible and retrieves the bounding rectangle, the return value is TRUE. Otherwise, the message returns FALSE and does not retrieve the bounding rectangle.

See Also

RECT


TVM_GETNEXTITEM  (preliminaryWindows NT)
TVM_GETNEXTITEM  (preliminary−Windows NT)

TVM_GETNEXTITEM

wParam = (WPARAM) (UINT) flag;

lParam = (LPARAM) (HTREEITEM) hitem;

// Corresponding macro

HTREEITEM TreeView_GetNextItem(hwnd, hitem, flag);

// Related macros

HTREEITEM TreeView_GetChild(hwnd, hitem);

HTREEITEM TreeView_GetDropHilite(hwnd);

HTREEITEM TreeView_GetFirstVisible(hwnd);

HTREEITEM TreeView_GetNextSibling(hwnd, hitem);

HTREEITEM TreeView_GetNextVisible(hwnd, hitem);

HTREEITEM TreeView_GetParent(hwnd, hitem);

HTREEITEM TreeView_GetPrevSibling(hwnd, hitem);

HTREEITEM TreeView_GetPrevVisible(hwnd, hitem);

HTREEITEM TreeView_GetRoot(hwnd);

HTREEITEM TreeView_GetSelection(hwnd);

Retrieves the tree-view item that bears the specified relationship to a specified item. You can send this message explicitly, or by using the TreeView_GetNextItem macro or one of the related macros.

Parameters

hwnd and hitem

Handle to the tree-view control, and the handle to an item.

flag

Flag specifying the item to retrieve. This parameter can be one of the following values:

Value	Message
TVGN_CARET	Retrieves the currently selected item.
TVGN_CHILD	Retrieves the first child item. The hitem parameter must be NULL.
TVGN_DROPHILITE	Retrieves the item that is the target of a drag-and-drop operation.
TVGN_FIRSTVISIBLE	Retrieves the first visible item.
TVGN_NEXT	Retrieves the next sibling item.
TVGN_NEXTVISIBLE	Retrieves the next visible item that follows the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible.
TVGN_PARENT	Retrieves the parent of the specified item.
TVGN_PREVIOUS	Retrieves the previous sibling item.
TVGN_PREVIOUSVISIBLE	Retrieves the first visible item that precedes the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible.
TVGN_ROOT	Retrieves the topmost or very first item of the tree-view control.
Return Value

Returns the handle to the item if successful or NULL otherwise.

See Also

TVM_GETITEMRECT


TVM_GETVISIBLECOUNT  (preliminaryWindows NT)
TVM_GETVISIBLECOUNT  (preliminary−Windows NT)

TVM_GETVISIBLECOUNT

wParam = 0;

lParam = 0;

// Corresponding macro

UINT TreeView_GetVisibleCount(hwnd);

The TVM_GETVISIBLECOUNT message obtains the number of items that are fully visible in the client window of a tree-view control. You can send this message explicitly, or by using the TreeView_GetVisibleCount macro.

Parameters

hwnd

Handle to the tree-view control.

Return Value

Returns the number of items that are fully visible in the client window of the tree-view control.

Remarks

Note that the return value is the number of fully-visible items. If you can see all of 20 items, and part of one more item, the return value is 20, not 21.


TVM_HITTEST  (preliminaryWindows NT)
TVM_HITTEST  (preliminary−Windows NT)

TV_HITTEST

wParam = 0;

lParam = (LPARAM) (LPTV_HITTESTINFO) lpht;

// Corresponding macro

HTREEITEM TreeView_HitTest(hwnd, lpht);

The TVM_HITTEST message determines the location of the specified point relative to the client area of a tree-view control. You can send this message explicitly or by using the TreeView_HitTest macro.

Parameters

hwnd

Handle to the tree-view control.

lpht

Pointer to a TV_HITTESTINFO structure. When the message is sent, the pt member specifies the coordinates of the point to test. When the message returns, the hItem member is the handle to the item at the specified point or NULL if no item occupies the point. Also, when the message returns, the flags member is a hit-test value that indicates the location of the specified point. For a list of hit-test values, see the description of the TV_HITTESTINFO structure.

Return Value

Returns the handle to the tree-view item that occupies the specified point or NULL if no item occupies the point.

See Also

TV_HITTESTINFO


TVM_INSERTITEM  (preliminaryWindows NT)
TVM_INSERTITEM  (preliminary−Windows NT)

TVM_INSERTITEM

wParam = 0;

lParam = (LPARAM) (LPTV_INSERTSTRUCT) lpis;

// Corresponding macro

HTREEITEM TreeView_InsertItem(hwnd, lpis);

The TVM_INSERTITEM message inserts a new item in a tree-view control. You can send this message explicitly or by using the TreeView_InsertItem macro.

Parameters

hwnd

Handle to the tree-view control.

lpis

Pointer to a TV_INSERTSTRUCT structure that specifies the attributes of the tree-view item.

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message.

Return Value

Returns the handle to the new item if successful or NULL otherwise.

See Also

TV_INSERTSTRUCT, TVN_ENDLABELEDIT


TVM_SELECTITEM  (preliminaryWindows NT)
TVM_SELECTITEM  (preliminary−Windows NT)

TV_SELECTITEM

wParam = (WPARAM) flag;

lParam = (LPARAM) (HTREEITEM) hitem;

// Corresponding macro

BOOL TreeView_Select(hwnd, hitem, flag);

// Related macros

BOOL TreeView_SelectDropTarget(hwnd, hitem);

BOOL TreeView_SelectItem(hwnd, hitem);

BOOL TreeView_SelectSetFirstVisible(hwnd, hitem);

The TVM_SELECTITEM message selects the specified tree-view item, scrolls the item into view, or redraws the item in the style used to indicate the target of a drag-and-drop operation. You can send this message explicitly or by using the TreeView_Select, TreeView_SelectItem, or TreeView_SelectDropTarget macro.

Parameters

hwnd and hitem

Handle to the tree-view control, and the handle to an item. If hitem is NULL, the selection is removed from the currently selected item, if any.

flag

Action flag. This parameter can be one of the following values:

Value	Meaning
TVGN_CARET	Sets the selection to the given item.
TVGN_DROPHILITE	Redraws the given item in the style used to indicate the target of a drag and drop operation.
TVGN_FIRSTVISIBLE	Scrolls the tree view vertically so that the given item is the first visible item.
Return Value

Returns TRUE if successful or FALSE otherwise.

Remarks

If the TVGN_CARET value is specified, the parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. Also, if the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectItem macro is equivalent to sending the TVM_SELECTITEM message with flag set to the TVGN_CARET value. Using the TreeView_SelectDropTarget macro is equivalent to sending the TVM_SELECTITEM message with flag set to the TVGN_DROPHILITE value. Using TreeView_SelectSetFirstVisible is equivalent to sending the TVM_SELECTITEM message with flag set to the TVGN_FIRSTVISIBLE value.

See Also

TVN_ITEMEXPANDED, TVN_ITEMEXPANDING, TVN_SELCHANGED, TVN_SELCHANGING


TVM_SETIMAGELIST  (preliminaryWindows NT)
TVM_SETIMAGELIST  (preliminary−Windows NT)

TVM_SETIMAGELIST

wParam = (WPARAM) iImage;

lParam = (LPARAM) (HIMAGELIST) himl;

// Corresponding macro

HIMAGELIST TreeView_SetImageList(hwnd, himl, iImage);

The TVM_SETIMAGELIST message sets the normal or state image list for a tree-view control and redraws the control using the new images. You can send this message explicitly or by using the TreeView_SetImageList macro.

Parameters

hwnd and himl

Handle to the tree-view control, and the handle to the image list. If himl is NULL, all images are removed from the tree-view control.

iImage

Type of image list to set. For a list of possible values, see the description of the TVM_GETIMAGELIST message.

Return Value

Returns the handle to the previous image list, if any, or NULL otherwise.

See Also

TVM_GETIMAGELIST


TVM_SETINDENT  (preliminaryWindows NT)
TVM_SETINDENT  (preliminary−Windows NT)

TVM_SETINDENT

wParam = (WPARAM) indent;

lParam = 0;

// Corresponding macro

BOOL TreeView_SetIndent(hwnd, indent);

The TVM_SETINDENT message sets the width of indentation for a tree-view control and redraws the control to reflect the new width. You can send this message explicitly or by using the TreeView_SetIndent macro.

Parameters

hwnd

Handle to the tree-view control.

indent

Width, in pixels, of the indentation. If this parameter is less than the system-defined minimum width, the new width is set to the system-defined minimum.

Return Value

No return value.


TVM_SETITEM  (preliminaryWindows NT)
TVM_SETITEM  (preliminary−Windows NT)

TVM_SETITEM

wParam = 0;

lParam = (LPARAM) (const TV_ITEM FAR*) pitem;

// Corresponding macro

BOOL TreeView_SetItem(hwnd, pitem);

The TVM_SETITEM sets some or all of a tree-view item's attributes. You can send this message explicitly or by using the TreeView_SetItem macro.

Parameters

hwnd

Handle to the tree-view control.

pitem

Pointer to a TV_ITEM structure that contains the new item attributes. The hItem member identifies the item, and the mask member specifies which attributes to set.

If mask specifies the TVIF_TEXT value, the pszText member is the pointer to a null-terminated string and the cchTextMax member is ignored.

If mask specifies the TVIF_STATE value, the stateMask member indicates which item states to change and the state member contains the values for those states.

Return Value

Returns zero if successful or  − 1 otherwise.

See Also

TV_ITEM


TVM_SORTCHILDREN  (preliminaryWindows NT)
TVM_SORTCHILDREN  (preliminary−Windows NT)

TVM_SORTCHILDREN

wParam = 0;  // reserved for future use; must be zero

lParam = (LPARAM) (HTREEITEM) hitem;

// Corresponding macro

BOOL TreeView_SortChildren(hwnd, hitem, fRecurse);

The TVM_SORTCHILDREN message sorts the child items of the specified parent item in a tree-view control. You can send this message explicitly or by using the TreeView_SortChildren macro.

Parameters

hwnd and hitem

Handle to the tree-view control, and the handle to the parent item whose child items are to be sorted.

fRecurse

Reserved for future use. Must be zero.

Return Value

Returns TRUE if successful or FALSE otherwise.


TVM_SORTCHILDRENCB  (preliminaryWindows NT)
TVM_SORTCHILDRENCB  (preliminary−Windows NT)

TVM_SORTCHILDRENCB

wParam = 0;  // reserved for future use; must be zero

lParam = (LPARAM) (LPTV_SORTCB) psort;

// Corresponding macro

BOOL TreeView_SortChildrenCB(hwnd, psort, fRecurse);

The TVM_SORTCHILDRENCB message sorts tree-view items using an application-defined callback function that compares the items. You can send this message explicitly or by using the TreeView_SortChildrenCB macro.

Parameters

hwnd

Handle to the tree-view control.

psort

Pointer to a TV_SORTCB structure. The lpfnCompare member is the pointer to the application-defined callback function, which is called during the sort operation each time the relative order of two list items needs to be compared. For more information about the callback function, see the description of TV_SORTCB.

fRecurse

Reserved for future use. Must be zero.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

TV_SORTCB


TVN_BEGINDRAG  (preliminaryWindows NT)
TVN_BEGINDRAG  (preliminary−Windows NT)

TVN_BEGINDRAG

pnmtv = (NM_TREEVIEW FAR *) lParam

The TVN_BEGINDRAG notification message notifies a tree-view control's parent window that a drag-and-drop operation involving the left mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemNew member is a TV_ITEM structure that contains valid information about the item being dragged in the hItem, state, and lParam members. The ptDrag member specifies the current screen coordinates of the mouse.

Return Value

No return value.

Remarks

A tree-view control that has the TVS_DISABLEDRAGDROP style does not send this notification message.

See Also

NM_TREEVIEW, TV_ITEM, WM_NOTIFY


TVN_BEGINLABELEDIT  (preliminaryWindows NT)
TVN_BEGINLABELEDIT  (preliminary−Windows NT)

TVN_BEGINLABELEDIT

ptvdi = (TV_DISPINFO FAR *) lParam

The TVN_BEGINLABELEDIT notification message notifies a tree-view control's parent window about the start of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

ptvdi

Pointer to a TV_DISPINFO structure. The item member is a TV_ITEM structure that contains valid information about the item being edited in the hItem, state, lParam, and pszText members.

Return Value

Returns TRUE to cancel label editing.

See Also

TV_DISPINFO, TV_ITEM, WM_NOTIFY


TVN_BEGINRDRAG  (preliminaryWindows NT)
TVN_BEGINRDRAG  (preliminary−Windows NT)

TVN_BEGINRDRAG

pnmtv = (NM_TREEVIEW FAR *) lParam

The TVN_BEGINRDRAG notification message notifies a tree-view control's parent window about the initiation of a drag-and-drop operation involving the right mouse button. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemNew member is a TV_ITEM structure that contains valid information in the hItem, state, and lParam members about the item to be dragged. The ptDrag member specifies the current screen coordinates of the mouse.

Return Value

No return value.

See Also

NM_TREEVIEW, TV_ITEM, WM_NOTIFY


TVN_DELETEITEM  (preliminaryWindows NT)
TVN_DELETEITEM  (preliminary−Windows NT)

TVN_DELETEITEM

pnmtv = (NM_TREEVIEW FAR *) lParam

The TVN_DELETEITEM notification message notifies a tree-view control's parent window that an item has been deleted. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemOld member is a TV_ITEM structure containing valid information about the item that was deleted in the hItem and lParam members.

Return Value

No return value.

See Also

NM_TREEVIEW, TV_ITEM, WM_NOTIFY


TVN_ENDLABELEDIT  (preliminaryWindows NT)
TVN_ENDLABELEDIT  (preliminary−Windows NT)

TVN_ENDLABELEDIT

ptvdi = (TV_DISPINFO FAR *) lParam

The TVN_ENDLABELEDIT notification message notifies a tree-view control's parent window about the end of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

ptvdi

Pointer to a TV_DISPINFOstructure. The item member is a TV_ITEM structure containing valid information about the item that was edited in the hItem, lParam, and pszText members. If label editing was canceled, the pszText member is zero.

Return Value

No return value.

See Also

WM_NOTIFY, TV_DISPINFO, TV_ITEM


TVN_GETDISPINFO  (preliminaryWindows NT)
TVN_GETDISPINFO  (preliminary−Windows NT)

TVN_GETDISPINFO

ptvdi = (TV_DISPINFO FAR *) lParam

The TVN_GETDISPINFO notification message requests that a tree-view control's parent window provide information needed to display or sort an item. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

ptvdi

Pointer to a TV_DISPINFO structure. The item member is a TV_ITEM structure whose mask, hItem, state, and lParam members specify the type of information required. You must fill the members of the structure with the appropriate information.

Return Value

No return value.

Remarks

See Also

TV_DISPINFO, TV_ITEM, WM_NOTIFY


TVN_ITEMEXPANDED  (preliminaryWindows NT)
TVN_ITEMEXPANDED  (preliminary−Windows NT)

TVN_ITEMEXPANDED

pnmtv = (NM_TREEVIEW FAR *) lParam

The TVN_ITEMEXPANDED notification message notifies a tree-view control's parent window that a parent item's list of child items has expanded or collapsed. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemNew member is a TV_ITEM structure that contains valid information about the parent item in the hItem, state, and lParam members. The action member indicates whether the list expanded or collapsed. For a list of possible values, see the description of the TVM_EXPAND message.

Return Value

No return value.

See Also

NM_TREEVIEW, TV_ITEM, TVM_EXPAND, WM_NOTIFY


TVN_ITEMEXPANDING  (preliminaryWindows NT)
TVN_ITEMEXPANDING  (preliminary−Windows NT)

TVN_ITEMEXPANDING

pnmtv = (NM_TREEVIEW FAR *) lParam

The TVN_ITEMEXPANDING notification message notifies a tree-view control's parent window that a parent item's list of child items is about to expand or collapse. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemNew member is a TV_ITEM structure that contains valid information about the parent item in the hItem, state, and lParam members. The action member indicates whether the list is to expand or collapse. For a list of possible values, see the description of the TVM_EXPAND message.

Return Value

Returns TRUE to prevent the list from expanding or collapsing.

See Also

NM_TREEVIEW, TV_ITEM, TVM_EXPAND, WM_NOTIFY


TVN_KEYDOWN  (preliminaryWindows NT)
TVN_KEYDOWN  (preliminary−Windows NT)

TVN_ITEMEXPANDING

ptvkd = (TV_KEYDOWN FAR *) lParam

The TVN_KEYDOWN notification message notifies a tree-view control's parent window that the user pressed a key and the tree-view control has the input focus. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

ptvkd

Pointer to a TV_KEYDOWN structure. The wVKey member specifies the virtual-key code.

Return Value

No return value.

See Also

TV_KEYDOWN, WM_NOTIFY


TVN_SELCHANGED  (preliminaryWindows NT)
TVN_SELCHANGED  (preliminary−Windows NT)

TVN_SELCHANGED

pnmtv = (NM_TREEVIEW FAR *) lParam

The TVN_SELCHANGED notification message notifies a tree-view control's parent window that the selection has changed from one item to another. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemOld and itemNew members are TV_ITEM structures that contain information about the previously selected item and the newly selected items in the hItem, state, and lParam members. The action member indicates the type of action that caused the selection to change; it can be one of the following values:

Value	Meaning
TVC_BYKEYBOARD	By a key stroke
TVC_BYMOUSE	By a mouse click
TVC_UNKNOWN	Unknown
Return Value

No return value.

See Also

NM_TREEVIEW, WM_NOTIFY


TVN_SELCHANGING  (preliminaryWindows NT)
TVN_SELCHANGING  (preliminary−Windows NT)

TVN_SELCHANGING

pnmtv = (NM_TREEVIEW FAR *) lParam

The TVN_SELCHANGING notification message notifies a tree-view control's parent window that the selection is about to change from one item to another. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

pnmtv

Pointer to an NM_TREEVIEW structure. The itemOld and itemNew members contain valid information about the currently selected item and the newly selected item. The action member indicates whether a mouse or keyboard action is causing the selection to change. For a list of possible values, see the description of the TVN_SELCHANGED notification message.

Return Value

Returns TRUE to prevent the selection from changing.

See Also

NM_TREEVIEW, TVN_SELCHANGED, WM_NOTIFY


TVN_SETDISPINFO  (preliminaryWindows NT)
TVN_SETDISPINFO  (preliminary−Windows NT)

TVN_SETDISPINFO

ptvdi = (TV_DISPINFO FAR *) lParam

The TVN_SETDISPINFO notification message notifies a tree-view control's parent window that it must update the information it maintains about an item. This notification message is sent in the form of a WM_NOTIFY message.

Parameters

ptvdi

Pointer to a TV_DISPINFO structure. The item member is a TV_ITEM structure that contains valid information about the item in the hItem and lParam members.

Return Value

No return value.

Remarks

The system sends this notification message when the user has finished editing the label of an item whose text is set to LPSTR_TEXTCALLBACK. The notification gives the parent window the opportunity to store the new item text.

See Also

TV_DISPINFO, TV_ITEM, WM_NOTIFY


UDM_GETACCEL  (preliminaryWindows NT)
UDM_GETACCEL  (preliminary−Windows NT)

UDM_GETACCEL

wParam = (WPARAM) cAccels;

lParam = (LPARAM) (LPUDACCEL) paAccels;

The UDM_GETACCEL message retrieves acceleration information for an up-down control.

Parameters

cAccels

Number of elements in the array specified by paAccels.

paAccels

Address of an array of UDACCEL structures that receives acceleration information.

Return Value

The return value is the number of accelerator structures retrieved.

See Also

UDACCEL


UDM_GETBASE  (preliminaryWindows NT)
UDM_GETBASE  (preliminary−Windows NT)

UDM_GETBASE

wParam = 0;

lParam = 0;

The UDM_GETBASE message retrieves the current radix base (that is, either base 10 or 16) for an up-down control.

Return Value

The return value is the current base value.


UDM_GETBUDDY  (preliminaryWindows NT)
UDM_GETBUDDY  (preliminary−Windows NT)

UDM_GETBUDDY

wParam = 0;

lParam = 0;

The UDM_GETBUDDY message retrieves the handle of the current buddy window.

Return Value

The return value is the handle of the current buddy window.


UDM_GETPOS  (preliminaryWindows NT)
UDM_GETPOS  (preliminary−Windows NT)

UDM_GETPOS

wParam = 0;

lParam = 0;

The UDM_GETPOS message retrieves the current position of an up-down control.

Return Value

The return value is the current position in the low-order word. If an error occurred, the high-order word is nonzero.

Remarks

When processing this message, the up-down control updates its current position based on the caption of the buddy window. The up-down control returns an error if there is no buddy window or if the caption specifies an invalid or out-of-range value.


UDM_GETRANGE  (preliminaryWindows NT)
UDM_GETRANGE  (preliminary−Windows NT)

UDM_GETRANGE

wParam = 0;

lParam = 0;

The UDM_GETRANGE message retrieves the minimum and maximum positions (range) for an up-down control.

Return Value

The return value is a 32-bit value that contains the minimum and maximum positions. The low-order word is the maximum position for the control, and the high-order word is the minimum position.


UDM_SETACCEL  (preliminaryWindows NT)
UDM_SETACCEL  (preliminary−Windows NT)

UDM_SETACCEL

wParam = (WPARAM) nAccels;

lParam = (LPARAM) (LPUDACCEL) aAccels;

The UDM_SETACCEL message sets the acceleration for an up-down control.

Parameters

nAccels

Number of UDACCEL structures specified by aAccels.

aAccels

Address of an array of UDACCEL structures that contains acceleration information. Elements should be sorted in ascending order based on the nSec member.

Return Value

Returns TRUE if successful or FALSE otherwise.

See Also

UDACCEL


UDM_SETBASE  (preliminaryWindows NT)
UDM_SETBASE  (preliminary−Windows NT)

UDM_SETBASE

wParam = (WPARAM) nBase;

lParam = 0;

The UDM_SETBASE message sets the radix base for an up-down control. The base value determines whether the buddy window displays numbers in decimal or hexadecimal digits. Hexadecimal numbers are always unsigned, and decimal numbers are signed.

Parameters

nBase

New base value for the control. This parameter can be 10 for decimal or 16 for hexadecimal.

Return Value

The return value is the previous base value. If an invalid base is given, the return value is zero.


UDM_SETBUDDY  (preliminaryWindows NT)
UDM_SETBUDDY  (preliminary−Windows NT)

UDM_SETBUDDY

wParam = (WPARAM) (HWND) hwndBuddy;

lParam = 0;

The UDM_SETBUDDY message sets the buddy window for an up-down control.

Parameters

hwndBuddy

Handle of the new buddy window.

Return Value

The return value is the handle of the previous buddy window.


UDM_SETPOS  (preliminaryWindows NT)
UDM_SETPOS  (preliminary−Windows NT)

UDM_SETPOS

wParam = 0;

lParam = (LPARAM) MAKELONG((short) nPos, 0);

The UDM_SETPOS message sets the current position for an up-down control.

Parameters

nPos

New position for the up-down control. This parameter must be in the range specified by the upper and lower limits for the control.

Return Value

The return value is the previous position.


UDM_SETRANGE  (preliminaryWindows NT)
UDM_SETRANGE  (preliminary−Windows NT)

UDM_SETRANGE

wParam = 0;

lParam = (LPARAM) MAKELONG((short) nUpper, (short) nLower);

The UDM_SETRANGE message sets the minimum and maximum positions (range) for an up-down control.

Parameters

nUpper and nLower

Maximum position and minimum position for the up-down control. Neither position can be greater than the UD_MAXVAL value or less than the UD_MINVAL value. In addition, the difference between the two positions cannot exceed UD_MAXVAL.

Return Value

No return value.

Remarks

The maximum position can be less than the minimum position. Clicking the up arrow moves the current position closer to the maximum position, and clicking the down arrow moves towards the minimum position.


UDN_DELTAPOS  (preliminaryWindows NT)
UDN_DELTAPOS  (preliminary−Windows NT)

UDN_DELTAPOS

pnmud = (NM_UPDOWN FAR *) lParam

The operating system sends the UDN_DELTAPOS notification message to the parent window of an up-down control when the position of the control is about to change. This happens when the user requests a change in the value by pressing the control's up or down arrow. The UDN_DELTAPOS message is sent before the WM_VSCROLL message that actually changes the control's position. This lets you examine, allow, modify, or disallow the change. The UDN_DELTAPOS message is sent in the form of a WM_NOTIFY message.

Parameters

pnmud

Pointer to an NM_UPDOWN structure that contains information about the position change.

The iPos member of this structure contains the current position of the control.

The iDelta member of the structure is a signed integer that contains the proposed change in position. If the user has clicked on the up button, this is a positive value. If the user has clicked on the down button, this is a negative value.

Return Value

Return TRUE in response to this message to prevent the change in the control's position.

Return FALSE to allow the change in the control's position.

See Also

NM_UPDOWN, WM_COMMAND, WM_VSCROLL


WM_ACTIVATE

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; it is then sent to the window procedure of the top-level window being activated.

Parameters

fActive

Value of the low-order word of wParam. Specifies whether the window is being activated or deactivated. This parameter can be one of the following values:

Value	Meaning
WA_ACTIVE	Activated by some method other than a mouse click (for example, by a call to the SetActiveWindow function or by use of the keyboard interface to select the window).
WA_CLICKACTIVE	Activated by a mouse click.
WA_INACTIVE	Deactivated.
fMinimized

Value of the high-order word of wParam. Specifies the minimized state of the window being activated or deactivated. A nonzero value indicates the window is minimized.

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.

Return Value

If an application processes this message, it should return zero.

Default Action

If the window is being activated and is not minimized, the DefWindowProc function sets the keyboard focus to the window.

Remarks

If the window is activated by a mouse click, it also receives a WM_MOUSEACTIVATE message.

See Also

DefWindowProc, SetActiveWindow, WM_MOUSEACTIVATE, WM_NCACTIVATE


WM_ACTIVATEAPP

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.

Parameters

fActive

Value of wParam. Specifies whether the window is being activated or deactivated. This parameter is TRUE if the window is being activated; it is FALSE if the window is being deactivated.

dwThreadID

Value of lParam. Specifies a thread identifier. If the fActive parameter is TRUE, dwThreadID is the identifier of the thread that owns the window being deactivated. If fActive is FALSE, dwThreadID is the identifier of the thread that owns the window being activated.

Return Value

If an application processes this message, it should return zero.

See Also

WM_ACTIVATE


WM_ASKCBFORMATNAME

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.

Parameters

cchName

Value of wParam. Specifies the size, in characters, of the buffer pointed to by the lpszFormatName parameter.

lpszFormatName

Value of lParam. Points to the buffer that is to receive the clipboard format name.

Return Value

If an application processes this message, it should return zero.

Remarks

In response to this message, the clipboard owner should copy the name of the owner-display format to the specified buffer, not exceeding the buffer size specified by the cchName parameter.

A clipboard viewer window sends this message to the clipboard owner to determine the name of the CF_OWNERDISPLAY format — for example, to initialize a menu listing available formats.


WM_CANCELJOURNAL

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.

Return Value

This message does not return a value. It is meant to be processed from within an application's main loop or a GetMessage hook procedure, not from a window procedure.

Remarks

Journal record and playback modes are modes imposed on the system that let an application sequentially record or play back user input. The system enters these modes when an application installs a JournalRecordProc or JournalPlaybackProc hook procedure. When the system is in either of these journaling modes, applications must take turns reading input from the input queue. If any one application stops reading input while the system is in a journaling mode, other applications are forced to wait.

To ensure a robust system, one that cannot be hung up by any one application, Windows NT automatically cancels any journalling activities when a user presses CTRL+ESC, ALT+ESC, or CTRL+ALT+DEL. The system then unhooks any journaling hook procedures, and posts a WM_CANCELJOURNAL message, with a NULL window handle, to the application that set the journaling hook.

Since the WM_CANCELJOURNAL has a NULL window handle, it cannot be dispatched to a window procedure. There are two ways for an application to see a WM_CANCELJOURNAL message: If the application is running in its own main loop, it must catch the message between its call to GetMessage or PeekMessage and its call to DispatchMessage. If the application is not running in its own main loop, it must set a GetMsgProc hook procedure (via a call to SetWindowsHookEx specifying the WH_GETMESSAGE hook type) that watches for the message.

When an application sees a WM_CANCELJOURNAL message, it can assume two things: the user has intentionally cancelled the journal record or playback mode, and the system has already unhooked any journal record or playback hook procedures.

Note that the key combinations mentioned above (CTRL+ESC, ALT+ESC, or CTRL+ALT+DEL) cause the system to cancel journaling. If any one application is hung, they give the user a means of recovery. The VK_CANCEL virtual keycode (usually implemented as the CTRL+BREAK key combination) is what an application that is in journal record mode should watch for as a signal that the user wishes to cancel the journaling activity. The difference is that watching for VK_CANCEL is a suggested behavior for journaling applications, whereas CTRL+ESC, ALT+ESC, or CTRL+ALT+DEL cause the system to cancel journalling regardless of a journalling application's behavior.

See Also

JournalPlaybackProc, JournalRecordProc, GetMsgProc, SetWindowsHookEx


WM_CANCELMODE

WM_CANCELMODE

The WM_CANCELMODE message is sent to the focus window when a dialog box or message box is displayed; this enables the focus window to cancel modes, such as mouse capture.

Parameters

This message has no parameters.

Return Value

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function cancels internal processing of standard scroll bar input, cancels internal menu processing, and releases the mouse capture.

See Also

DefWindowProc, ReleaseCapture


WM_CAPTURECHANGED  (preliminaryWindows 95)
WM_CAPTURECHANGED  [image]  (preliminary−Windows 95)

WM_CAPTURECHANGED

hwndNewCapture = (HWND) lParam;    // handle of window to gain mouse capture

The WM_CAPTURECHANGED message is sent to the window that is losing the mouse capture.

Parameters

hwndNewCapture

Value of lParam. Identifies the window that is gaining the mouse capture.

Return Value

An application should return zero if it processes this message.

Remarks

A window receives this message even if it calls ReleaseCapture itself. An application should not attempt to set the mouse capture in response to this message.

When it receives this message, a window should redraw itself, if necessary, to reflect the new mouse-capture state.

See Also

ReleaseCapture, SetCapture


WM_CHANGECBCHAIN

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.

Parameters

hwndRemove

Value of wParam. Identifies the window being removed from the clipboard viewer chain.

hwndNext

Value of lParam. Identifies the next window in the chain following the window being removed. This parameter is NULL if the window being removed is the last window in the chain.

Return Value

If an application processes this message, it should return zero.

Remarks

Each clipboard viewer window saves the handle of the next window in the clipboard viewer chain. Initially, this handle is the return value of the SetClipboardViewer function.

When a clipboard viewer window receives the WM_CHANGECBCHAIN message, it should call the SendMessage function to pass the message to the next window in the chain, unless the next window is the window being removed. In this case, the clipboard viewer should save the handle specified by hwndNext as the next window in the chain.

See Also

SendMessage, SetClipboardViewer


WM_CHAR

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.

Parameters

chCharCode

Value of wParam. Specifies the character code of the key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag, context code, previous key-state flag, and transition-state flag, as shown in the following table:

Value	Description
0−15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16−23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM).
24	Specifies whether the key is an extended key, such as the right-hand ALT and CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if it is an extended key; otherwise, it is 0.
25−28	Reserved; do not use.
29	Specifies the context code. The value is 1 if the ALT key is held down while the key is pressed; otherwise, the value is 0.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent, or it is 0 if the key is up.
31	Specifies the transition state. The value is 1 if the key is being released, or it is 0 if the key is being pressed.
Return Value

An application should return zero if it processes this message.

Remarks

Because there is not necessarily a one-to-one correspondence between keys pressed and character messages generated, the information in the high-order word of the lKeyData parameter is generally not useful to applications. The information in the high-order word applies only to the most recent WM_KEYDOWN message that precedes the posting of the WM_CHAR message.

For enhanced 101- and 102-key keyboards, extended keys are the right ALT and the right CTRL keys on the main section of the keyboard; the INS, DEL, HOME, END, PAGE UP, PAGE DOWN and arrow keys in the clusters to the left of the numeric keypad; and the divide (/) and ENTER keys in the numeric keypad. Some other keyboards may support the extended-key bit in the lKeyData parameter.

See Also

TranslateMessage, WM_KEYDOWN


WM_CHARTOITEM

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.

Parameters

nKey

Value of the low-order word of wParam. Specifies the value of the key the user pressed.

nCaretPos

Value of the high-order word of wParam. Specifies the current position of the caret.

hwndListBox

Value of lParam. Identifies the list box.

Return Value

The return value specifies the action that the application performed in response to the message. A return value of −1 or −2 indicates that the application handled all aspects of selecting the item and requires no further action by the list box. A return value of 0 or greater specifies the zero-based index of an item in the list box and indicates that the list box should perform the default action for the keystroke on the given item.

Default Action

The DefWindowProc function returns −1.

Remarks

Only owner-drawn list boxes that do not have the LBS_HASSTRINGS style can receive this message.

See Also

DefWindowProc, WM_CHAR, WM_VKEYTOITEM


WM_CHILDACTIVATE

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.

Return Value

If an application processes this message, it should return zero.

See Also

MoveWindow, SetWindowPos


WM_CHOOSEFONT_GETLOGFONT

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.

Parameters

lplf

Points to a LOGFONT structure that receives information about the current logical font.

Return Value

This message does not return a value.

Remarks

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

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.

Return Value

This message does not return a value.

Remarks

The deletion performed by the WM_CLEAR message can be undone by sending the edit control an EM_UNDO message.

To delete the current selection and place the deleted content on the clipboard, use the WM_CUT message.

When sent to a combo box, the WM_CLEAR message is handled by its edit control. This message has no effect when sent to a combo box with the CBS_DROPDOWNLIST style.

See Also

EM_UNDO, WM_COPY, WM_CUT, WM_PASTE


WM_CLOSE

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.

Return Value

If an application processes this message, it should return zero.

Default Action

The DefWindowProc function calls the DestroyWindow function to destroy the window.

Remarks

An application can prompt the user for confirmation, prior to destroying a window, by processing the WM_CLOSE message and calling the DestroyWindow function only if the user confirms the choice.

See Also

DefWindowProc, DestroyWindow


WM_COMMAND

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.

Parameters

wNotifyCode

Value of the high-order word of wParam. Specifies the notification code if the message is from a control. If the message is from an accelerator, this parameter is 1. If the message is from a menu, this parameter is 0.

wID

Value of the low-order word of wParam. Specifies the identifier of the menu item, control, or accelerator.

hwndCtl

Value of lParam. Identifies the control sending the message if the message is from a control. Otherwise, this parameter is NULL.

Return Value

If an application processes this message, it should return zero.

Remarks

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

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.

Parameters

wCompactRatio

Value of wParam. Specifies the ratio of central processing unit (CPU) time currently spent by Windows compacting memory to CPU time currently spent by Windows performing other operations. For example, 0x8000 represents 50 percent of CPU time spent compacting memory.

Return Value

If an application processes this message, it should return zero.

Remarks

When an application receives this message, it should free as much memory as possible, taking into account the current level of activity of the application and the total number of applications running with Windows.


WM_COMPAREITEM

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.

Parameters

idCtl

Value of wParam. Specifies the identifier of the control that sent the WM_COMPAREITEM message.

lpcis

Value of lParam. Points to a COMPAREITEMSTRUCT structure that contains the identifiers and application-supplied data for two items in the combo or list box.

Return Value

The return value indicates the relative position of the two items. It may be any of the following:

Value	Meaning
−1	Item 1 precedes item 2 in the sorted order.
0	Items 1 and 2 are equivalent in the sorted order.
1	Item 1 follows item 2 in the sorted order.
Remarks

When the owner of an owner-drawn combo box or list box receives this message, the owner returns a value indicating which of the items specified by the COMPAREITEMSTRUCT structure will appear before the other. Typically, Windows sends this message several times until it determines the exact position for the new item.

See Also

COMPAREITEMSTRUCT


AbortProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


acmDriverEnumCallback

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverProc

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	msacm.h
Unicode	No
Platform Notes	None


acmFilterChooseHookProc

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFilterEnumCallback

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFilterTagEnumCallback

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatChooseHookProc

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatEnumCallback

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatTagEnumCallback

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmStreamConvertCallback

Windows NT
Win95	Yes
Win32s
Import Library
Header File
Unicode
Platform Notes	None


AddPropSheetPageProc

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	prsht.h
Unicode
Platform Notes	None


CallWndProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CallWndRetProc

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	winuser.h
Unicode
Platform Notes	None


CBTProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CplApplet

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


DdeCallback

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode	No
Platform Notes	None


DebugProc

Windows NT	Yes
Win95
Win32s
Import Library
Header File	winuser.h
Unicode
Platform Notes	None


DialogProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawStateProc

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	winuser.h
Unicode
Platform Notes	None


DriverProc

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode
Platform Notes	None


EditWordBreakProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EnhMetaFileProc

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


EnumCalendarInfoProc

Windows NT	New
Win95	No
Win32s	New
Import Library	user-defined
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumChildProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumCodePagesProc

Windows NT	New
Win95	No
Win32s	New
Import Library	user-defined
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumDateFormatsProc

Windows NT	New
Win95	No
Win32s	New
Import Library	user-defined
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumDesktopProc

Windows NT	Yes
Win95
Win32s
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EnumFontFamExProc

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	wingdi.h
Unicode
Platform Notes	None


EnumFontFamProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


EnumFontsProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


EnumICMProfilesProc

Windows NT
Win95	Yes
Win32s
Import Library
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


EnumLocalesProc

Windows NT	New
Win95	No
Win32s	New
Import Library	user-defined
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumMetaFileProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


EnumObjectsProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


EnumRegisterWordProc

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


EnumResLangProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winbase.h
Unicode	No
Platform Notes	None


EnumResNameProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winbase.h
Unicode	No
Platform Notes	None


EnumResTypeProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user-defined
Header File	winbase.h
Unicode	No
Platform Notes	None


EnumThreadWndProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumTimeFormatsProc

Windows NT	New
Win95	No
Win32s	New
Import Library	user-defined
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumWindowsProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumWindowStationProc

Windows NT	New
Win95
Win32s
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ExtensionPropSheetPageProc

Windows NT
Win95	Yes
Win32s
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


FileIOCompletionRoutine

Windows NT	Yes
Win95
Win32s
Import Library
Header File	winbase.h
Unicode
Platform Notes	None


FMExtensionProc

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


ForegroundIdleProc

Windows NT	Yes
Win95
Win32s
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMsgProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


IOProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


JournalPlaybackProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


JournalRecordProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


KeyboardProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LineDDAProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


MessageProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


MidiInProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MidiOutProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MidiProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MouseProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


MyStatusProc

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h
Unicode
Platform Notes	None


OutputProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


PropEnumProc

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


PropEnumProcEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


PropSheetPageProc

Windows NT
Win95	Yes
Win32s
Import Library
Header File	prsht.h
Unicode	WinNT
Platform Notes	None


PropSheetProc

Windows NT
Win95	Yes
Win32s
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


RasDialFunc

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ras.h
Unicode	No
Platform Notes	None


RasDialFunc1

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ras.h
Unicode	No
Platform Notes	None


SendAsyncProc

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


ShellProc

Windows NT	Yes
Win95
Win32s
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


SoundSentryProc

Windows NT	Yes
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


SysMsgProc

Windows NT	Yes
Win95
Win32s
Import Library
Header File	winuser.h
Unicode
Platform Notes	None


TimeProc

Windows NT	Yes
Win95
Win32s
Import Library
Header File	mmsystem.h
Unicode
Platform Notes	None


TimerProc

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user-defined
Header File	winuser.h
Unicode	No
Platform Notes	None


waveInProc

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode
Platform Notes	None


waveOutProc

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode
Platform Notes	None


WaveProc

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode
Platform Notes	None


WindowProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode
Platform Notes	None


BS_3STATE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_AUTO3STATE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_AUTOCHECKBOX

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_AUTORADIOBUTTON

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_BITMAP

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_BOTTOM

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_CENTER

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_CHECKBOX

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_DEFPUSHBUTTON

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_DIBPATTERN

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Only supports 8x8 brushes


BS_DIBPATTERN8X8

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


BS_DIBPATTERNPT

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


BS_GROUPBOX

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_HATCHED

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


BS_HOLLOW

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


BS_ICON

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_INDEXED

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


BS_LEFT

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_MULTILINE

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_NOTIFY

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_NULL

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


BS_OWNERDRAW

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_PATTERN

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


BS_PATTERN8X8

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


BS_PUSHBUTTON

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_PUSHLIKE

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_RADIOBUTTON

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_RIGHT

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_RIGHTBUTTON

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_SOLID

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


BS_TEXT

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_TOP

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BS_VCENTER

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_AUTOHSCROLL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_DISABLENOSCROLL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_DROPDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_DROPDOWNLIST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_HASSTRINGS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_NOINTEGRALHEIGHT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_OEMCONVERT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_OWNERDRAWFIXED

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_OWNERDRAWVARIABLE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_SIMPLE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_SORT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSidIdentifierAuthority

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSidLengthRequired

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSidSubAuthority

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSidSubAuthorityCount

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


getsockname

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


getsockopt

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


GetStartupInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetStdHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetStockObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetStretchBltMode

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetStringTypeA

Windows NT	New
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	Unicode
Platform Notes	None


GetStringTypeEx

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


GetStringTypeW

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winnls.h
Unicode	Unicode
Platform Notes	None


GetSubMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSysColor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSysColorBrush

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSysModalWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSystemDefaultLangID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


GetSystemDefaultLCID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


GetSystemDirectory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetSystemInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSystemMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSystemMetrics

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSystemPaletteEntries

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetSystemPaletteUse

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetSystemPowerStatus

Windows NT
Win95	Yes
Win32s	No
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSystemTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSystemTimeAdjustment

Windows NT	New
Win95	No
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSystemTimeAsFileTime

Windows NT	New
Win95	No
Win32s
Import Library
Header File
Unicode	No
Platform Notes	None


GetTabbedTextExtent

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetTapeParameters

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTapePosition

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTapeStatus

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTempFileName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetTempPath

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetTextAlign

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetTextCharacterExtra

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetTextCharset

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetTextColor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetTextExtentExPoint

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: int == 16 bits


GetTextExtentPoint

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: int == 16 bits


GetTextExtentPoint32

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: int == 16 bits


GetTextFace

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetTextMetrics

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetThreadContext

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetThreadDesktop

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: NOP; only one desktop


GetThreadLocale

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	Windows 95: Locales are static & can change only at system boot


GetThreadPriority

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetThreadSelectorEntry

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetThreadTimes

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTickCount

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTimeFormat

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetTimeZoneInformation

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTokenInformation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetTopWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetTypeByName

Windows NT	Yes
Win95
Win32s	No
Import Library	wsock32.dll
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


GetUpdateRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetUpdateRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetUserDefaultLangID

Windows NT	Yes
Win95	Yes
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


GetUserDefaultLCID

Windows NT	Yes
Win95	Yes
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


GetUserName

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetUserObjectInformation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetUserObjectSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetVersion

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetVersionEx

Windows NT	New
Win95	Yes
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetViewportExtEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetViewportOrgEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetVolumeInformation

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowContextHelpId

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowDC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowExtEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetWindowLong

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetWindowOrgEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetWindowPlacement

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowRgn

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowsDirectory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetWindowTask

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetWindowTextLength

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetWindowThreadProcessId

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWindowWord

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetWinMetaFileBits

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetWorldTransform

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


glAccum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glAlphaFunc

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glBegin

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glBitmap

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glBlendFunc

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glCallList

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glCallLists

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glClear

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glClearAccum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glClearColor

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glClearDepth

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glClearIndex

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glClearStencil

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glClipPlane

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3b

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3bv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3ub

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3ubv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3ui

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3uiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3us

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor3usv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4b

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4bv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4ub

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4ubv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4ui

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4uiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4us

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColor4usv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColorMask

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glColorMaterial

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glCopyPixels

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glCullFace

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glDeleteLists

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glDepthFunc

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glDepthMask

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glDepthRange

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glDisable

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glDrawBuffer

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glDrawPixels

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEdgeFlag

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEdgeFlagv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEnable

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEnd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEndList

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalCoord1d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalCoord1dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalCoord1f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalCoord1fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalCoord2d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalCoord2dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalCoord2f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalCoord2fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalMesh1

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalMesh2

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalPoint1

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glEvalPoint2

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glFeedbackBuffer

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glFinish

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glFlush

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glFogf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glFogfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glFogi

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glFogiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glFrontFace

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glFrustum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGenLists

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetBooleanv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetClipPlane

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetDoublev

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetError

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetFloatv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetIntegerv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetLightfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetLightiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetMapdv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetMapfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetMapiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetMaterialfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetMaterialiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetPixelMapfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetPixelMapuiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetPixelMapusv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetPolygonStipple

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetString

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetTexEnvfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetTexEnviv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetTexGendv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetTexGenfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetTexGeniv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetTexImage

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetTexLevelParameterfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetTexLevelParameteriv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetTexParameterfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glGetTexParameteriv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glHint

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIndexd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIndexdv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIndexf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIndexfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIndexi

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIndexiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIndexMask

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIndexs

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIndexsv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glInitNames

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIsEnabled

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glIsList

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLightf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLightfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLighti

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLightiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLightModelf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLightModelfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLightModeli

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLightModeliv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLineStipple

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLineWidth

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glListBase

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLoadIdentity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLoadMatrixd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLoadMatrixf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLoadName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glLogicOp

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMap1d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMap1f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMap2d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMap2f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMapGrid1d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMapGrid1f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMapGrid2d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMapGrid2f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMaterialf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMaterialfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMateriali

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMaterialiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMatrixMode

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMultMatrixd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glMultMatrixf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNewList

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNormal3b

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNormal3bv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNormal3d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNormal3dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNormal3f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNormal3fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNormal3i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNormal3iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNormal3s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glNormal3sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


GlobalAddAtom

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GlobalAlloc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	GMEM_FIXED is expensive (locks pages) on Win32s - use GMEM_MOVEABLE


GlobalCompact

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalDeleteAtom

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalDiscard

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalFindAtom

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GlobalFlags

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalFree

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalGetAtomName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GlobalHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalLock

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalLRUNewest

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalLRUOldest

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalMemoryStatus

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalReAlloc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalSize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GlobalUnlock

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


glOrtho

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPassThrough

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPixelMapfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPixelMapuiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPixelMapusv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPixelStoref

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPixelStorei

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPixelTransferf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPixelTransferi

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPixelZoom

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPointSize

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPolygonMode

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPolygonStipple

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPopAttrib

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPopMatrix

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPopName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPushAttrib

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPushMatrix

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glPushName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos2d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos2dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos2f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos2fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos2i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos2iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos2s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos2sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos3d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos3dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos3f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos3fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos3i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos3iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos3s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos3sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos4d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos4dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos4f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos4fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos4i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos4iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos4s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRasterPos4sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glReadBuffer

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glReadPixels

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRectd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRectdv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRectf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRectfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRecti

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRectiv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRects

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRectsv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRenderMode

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRotated

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glRotatef

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glScaled

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glScalef

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glScissor

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glSelectBuffer

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glShadeModel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glStencilFunc

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glStencilMask

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glStencilOp

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord1d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord1dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord1f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord1fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord1i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord1iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord1s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord1sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord2d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord2dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord2f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord2fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord2i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord2iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord2s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord2sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord3d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord3dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord3f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord3fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord3i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord3iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord3s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord3sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord4d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord4dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord4f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord4fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord4i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord4iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord4s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexCoord4sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexEnvf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexEnvfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexEnvi

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexEnviv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexGend

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexGendv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexGenf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexGenfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexGeni

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexGeniv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexImage1D

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexImage2D

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexParameterf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexParameterfv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexParameteri

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTexParameteriv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTranslated

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glTranslatef

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


gluBeginCurve

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluBeginPolygon

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluBeginSurface

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluBeginTrim

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluBuild1DMipmaps

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluBuild2DMipmaps

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluCylinder

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluDeleteNurbsRenderer

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluDeleteQuadric

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluDeleteTess

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluDisk

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluEndCurve

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluEndPolygon

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluEndSurface

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluEndTrim

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluErrorString

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluErrorUnicodeStringEXT

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	WinNT
Platform Notes	None


gluGetNurbsProperty

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluLoadSamplingMatrices

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluLookAt

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluNewNurbsRenderer

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluNewQuadric

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluNewTess

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluNextContour

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluNurbsCallback

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluNurbsCurve

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluNurbsProperty

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluNurbsSurface

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluOrtho2D

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluPartialDisk

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluPerspective

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluPickMatrix

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluProject

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluPwlCurve

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluQuadricCallback

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluQuadricDrawStyle

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluQuadricNormals

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluQuadricOrientation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluQuadricTexture

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluScaleImage

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluSphere

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluTessCallback

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluTessVertex

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


gluUnProject

Windows NT	Yes
Win95	No
Win32s	No
Import Library	glu32.dll
Header File	glu.h
Unicode	No
Platform Notes	None


glVertex2d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex2dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex2f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex2fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex2i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex2iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex2s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex2sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex3d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex3dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex3f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex3fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex3i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex3iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex3s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex3sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex4d

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex4dv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex4f

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex4fv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex4i

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex4iv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex4s

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glVertex4sv

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


glViewport

Windows NT	Yes
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	gl.h
Unicode	No
Platform Notes	None


GrayString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


Handler

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File
Unicode	No
Platform Notes	None


HandlerRoutine

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File
Unicode	No
Platform Notes	None


HeapAlloc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapCompact

Windows NT	New
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapCreate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapDestroy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapFree

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapLock

Windows NT	New
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapReAlloc

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapSize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapUnlock

Windows NT	New
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapValidate

Windows NT	New
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HeapWalk

Windows NT	New
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


HideCaret

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


HiliteMenuItem

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


htonl

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


htons

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


I_BrowserDebugTrace

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_BrowserQueryOtherDomains

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_BrowserQueryStatistics

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_BrowserResetNetlogonState

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_BrowserResetStatistics

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_BrowserServerEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmbrowsr.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_NetLogonControl

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_NetLogonControl2

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


I_RpcAllocate

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcBindingCopy

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcBindingInqDynamicEndpoint

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcBindingInqTransportType

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode	No
Platform Notes	None


I_RpcBindingIsClientLocal

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcClearMutex

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcDeleteMutex

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcFree

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcFreeBuffer

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcGetAssociationContext

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcGetBuffer

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcGetCurrentCallHandle

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcIfInqTransferSyntaxes

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcMapWin32Status

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpc.h
Unicode
Platform Notes	None


I_RpcMonitorAssociation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcNsBindingSetEntryName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcNsGetBuffer

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsip.h
Unicode
Platform Notes	None


I_RpcNsRaiseException

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsip.h
Unicode
Platform Notes	None


I_RpcNsSendReceive

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsip.h
Unicode
Platform Notes	None


I_RpcPauseExecution

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcReBindBuffer

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcns4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcRequestMutex

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcSendReceive

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcServerRegisterForwardFunction

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode	No
Platform Notes	None


I_RpcSetAssociationContext

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_RpcSsDontSerializeContext

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode	No
Platform Notes	None


I_RpcStopMonitorAssociation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


I_UuidCreate

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdcep.h
Unicode
Platform Notes	None


ICClose

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


ICCompress

Windows NT	New
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressorChoose

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressorFree

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompress

Windows NT	New
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressEx

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressExBegin

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressExQuery

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDraw

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawBegin

Windows NT	New
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetDisplayFormat

Windows NT	New
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetInfo

Windows NT	New
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICImageCompress

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICImageDecompress

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICInstall

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICLocate

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICOpen

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICOpenFunction

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICRemove

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSendMessage

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSeqCompressFrame

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSeqCompressFrameEnd

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSeqCompressFrameStart

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSetState

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICSetStatusProc

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h
Unicode
Platform Notes	None


IIDFromString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


ImageList_Add

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_AddIcon

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_AddMasked

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_BeginDrag

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Create

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Destroy

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_DragEnter

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_DragLeave

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_DragMove

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_DragShowNolock

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Draw

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_DrawEx

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_EndDrag

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_ExtractIcon

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetBkColor

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetDragImage

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetIcon

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetIconSize

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetImageCount

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_GetImageInfo

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_LoadBitmap

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_LoadImage

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


ImageList_Merge

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Read

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Remove

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Replace

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_ReplaceIcon

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_SetBkColor

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_SetDragCursorImage

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_SetIconSize

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_SetOverlayImage

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImageList_Write

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ImmAssociateContext

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmConfigureIME

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmCreateContext

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmDestroyContext

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmEnumRegisterWord

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmEscape

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetCandidateList

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetCandidateListCount

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetCandidateWindow

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmGetCompositionFont

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetCompositionString

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetCompositionWindow

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmGetContext

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmGetConversionList

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetConversionStatus

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmGetDefaultIMEWnd

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmGetDescription

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetGuideLine

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetIMEFileName

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetOpenStatus

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmGetProperty

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmGetRegisterWordStyle

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmGetStatusWindowPos

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmGetVirtualKey

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmInstallIME

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmIsIME

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmIsUIMessage

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmNotifyIME

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmRegisterWord

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmReleaseContext

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmSetCandidateWindow

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmSetCompositionFont

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmSetCompositionString

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImmSetCompositionWindow

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmSetConversionStatus

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmSetOpenStatus

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmSetStatusWindowPos

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmSimulateHotKey

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode
Platform Notes	None


ImmUnregisterWord

Windows NT
Win95	Yes
Win32s
Import Library
Header File	imm.h
Unicode	WinNT
Platform Notes	None


ImpersonateDdeClientWindow

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	dde.h
Unicode	No
Platform Notes	None


ImpersonateLoggedOnUser

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


ImpersonateNamedPipeClient

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ImpersonateSelf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


inet_addr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


inet_ntoa

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


InflateRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


InitAtomTable

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


InitCommonControls

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


InitializeAcl

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


InitializeCriticalSection

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


InitializeSecurityDescriptor

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


InitializeSid

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


InitiateSystemShutdown

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


InSendMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


InsertMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


InsertMenuItem

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


Int32x32To64

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


Int64ShllMod32

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


Int64ShraMod32

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


Int64ShrlMod32

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


InterlockedDecrement

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


InterlockedExchange

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


InterlockedIncrement

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


IntersectClipRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


IntersectRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


InvalidateRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


InvalidateRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


InvertRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


InvertRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ioctlsocket

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


IsAccelerator

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


IsBadCodePtr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


IsBadHugeReadPtr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


IsBadHugeWritePtr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


IsBadReadPtr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


IsBadStringPtr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


IsBadWritePtr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


IsCharAlpha

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


IsCharAlphaNumeric

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


IsCharLower

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


IsCharUpper

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


IsChild

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


IsClipboardFormatAvailable

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


IsDBCSLeadByte

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


IsDBCSLeadByteEx

Windows NT	Yes
Win95
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


IsDialogMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


IsDlgButtonChecked

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


IsEqualGUID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


IsIconic

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


IsMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


IsRectEmpty

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


IsTextUnicode

Windows NT	New
Win95	No
Win32s	New
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


IsValidAcl

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


IsValidCodePage

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


IsValidLocale

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


IsValidPtrOut

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


IsValidSecurityDescriptor

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


IsValidSid

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


IsWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


IsWindowEnabled

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


IsWindowUnicode

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


IsWindowVisible

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


IsZoomed

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


joyGetDevCaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


joyGetNumDevs

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joyGetPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joyGetThreshold

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joyReleaseCapture

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joySetCapture

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


joySetThreshold

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


keybd_event

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


KillTimer

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


LBItemFromPt

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


LCMapString

Windows NT	New
Win95	Yes
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


LeaveCriticalSection

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LHashValOfNameSys

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


LineDDA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


LineTo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


listen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


LoadAccelerators

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadBitmap

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadCursor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadCursorFromFile

Windows NT	New
Win95	New
Win32s	New
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadIcon

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadImage

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


LoadImageColorMatcher

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


LoadKeyboardLayout

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	Windows 95: Only 1 keybrd loaded at once


LoadLibrary

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LoadLibraryEx

Windows NT	Yes
Win95	Yes
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	Windows 95 limitations


LoadMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadMenuIndirect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadModule

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LoadRegTypeLib

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


LoadResource

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LoadString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


LoadTypeLib

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


LocalAlloc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalCompact

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalDiscard

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalFileTimeToFileTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalFlags

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalFree

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalLock

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalReAlloc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalShrink

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalSize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LocalUnlock

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LockFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LockFileEx

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LockResource

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


LockSegment

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


LockServiceDatabase

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	No
Platform Notes	None


LockWindowUpdate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


LogonUser

Windows NT	Yes
Win95
Win32s
Import Library
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


long_array_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


long_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


long_from_ndr_temp

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


LookupAccountName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LookupAccountSid

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LookupIconIdFromDirectory

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


LookupIconIdFromDirectoryEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


LookupPrivilegeDisplayName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LookupPrivilegeName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LookupPrivilegeValue

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


LPtoDP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


lstrcat

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


lstrcmp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


lstrcmpi

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


lstrcpy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


lstrcpyn

Windows NT	New
Win95	Yes
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


lstrlen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	1712
Platform Notes	,Widened,WinNT, Win95


LZClose

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.dll
Header File	lzexpand.h
Unicode	No
Platform Notes	None


LZCopy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.dll
Header File	lzexpand.h
Unicode	No
Platform Notes	None


LZDone

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.dll
Header File	lzexpand.h
Unicode	No
Platform Notes	None


LZInit

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.dll
Header File	lzexpand.h
Unicode	No
Platform Notes	None


LZOpenFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.dll
Header File	lzexpand.h
Unicode	WinNT
Platform Notes	None


LZRead

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.dll
Header File	lzexpand.h
Unicode	No
Platform Notes	None


LZSeek

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.dll
Header File	lzexpand.h
Unicode	No
Platform Notes	None


LZStart

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.dll
Header File	lzexpand.h
Unicode	No
Platform Notes	None


MakeAbsoluteSD

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


MakeDragList

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


MakeProcInstance

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


MakeSelfRelativeSD

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


MapDialogRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


MapGenericMask

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


MapViewOfFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95: Memory mapped files appear in the same address space in all processes


MapViewOfFileEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95: Memory mapped files appear in the same address space in all processes


MapVirtualKey

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


MapVirtualKeyEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


MapWindowPoints

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


MaskBlt

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


mciGetCreatorTask

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mciGetDeviceID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mciGetDeviceIDFromElementID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mciGetErrorString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mciGetYieldProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mciSendCommand

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mciSendString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mciSetYieldProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MenuHelp

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


MenuItemFromPoint

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


MesBufferHandleReset

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	midles.h
Unicode	No
Platform Notes	None


MesDecodeBufferHandleCreate

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	midles.h
Unicode	No
Platform Notes	None


MesDecodeIncrementalHandleCreate

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	midles.h
Unicode	No
Platform Notes	None


MesEncodeDynBufferHandleCreate

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	midles.h
Unicode	No
Platform Notes	None


MesEncodeFixedBufferHandleCreate

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	midles.h
Unicode	No
Platform Notes	None


MesEncodeIncrementalHandleCreate

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	midles.h
Unicode	No
Platform Notes	None


MesHandleFree

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	midles.h
Unicode	No
Platform Notes	None


MesIncrementalHandleReset

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	midles.h
Unicode	No
Platform Notes	None


MesInqProcEncodingId

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	midles.h
Unicode	No
Platform Notes	None


MessageBeep

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


MessageBox

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT; Win95
Platform Notes	None


MessageBoxEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT; Win95
Platform Notes	None


MessageBoxIndirect

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


midiConnect

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiDisconnect

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInAddBuffer

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInClose

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInGetDevCaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


midiInGetErrorText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


midiInGetID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInGetNumDevs

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInOpen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInPrepareHeader

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInReset

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInStart

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInStop

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiInUnprepareHeader

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutCacheDrumPatches

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutCachePatches

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutClose

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutGetDevCaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


midiOutGetErrorText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


midiOutGetID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutGetNumDevs

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutGetVolume

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutLongMsg

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutOpen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutPrepareHeader

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutReset

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutSetVolume

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutShortMsg

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiOutUnprepareHeader

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamClose

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamOpen

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamOut

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamPause

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamPosition

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamProperty

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamRestart

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midiStreamStop

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


midl_allocate

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	rpcndr.h
Unicode
Platform Notes	None


MIDL_user_allocate

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user defined
Header File	rpcndr.h
Unicode
Platform Notes	None


MIDL_wchar_strcpy

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


MIDL_wchar_strlen

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


mixerClose

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mixerGetControlDetails

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mixerGetDevCaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mixerGetID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mixerGetLineControls

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mixerGetLineInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mixerGetNumDevs

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mixerMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mixerOpen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mixerSetControlDetails

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MkParseDisplayName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


mmioAdvance

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioAscend

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioClose

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioCreateChunk

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioDescend

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioFlush

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioGetInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioInstallIOProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mmioOpen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mmioRead

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioRename

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mmioSeek

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioSendMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioSetBuffer

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioSetInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmioStringToFOURCC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


mmioWrite

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


mmsystemGetVersion

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


ModifyMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ModifyWorldTransform

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


MonikerCommonPrefixWith

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


MonikerRelativePathTo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


mouse_event

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


MoveFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


MoveFileEx

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


MoveMemory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


MoveToEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


MoveWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


MsgWaitForMultipleObjects

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


MulDiv

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


MultiByteToWideChar

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


NDdeGetErrorString

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeGetShareSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeGetTrustedShare

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeIsValidAppTopicList

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeIsValidShareName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeSetShareSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeSetTrustedShare

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeShareAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeShareDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeShareEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeShareGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeShareSetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDdeTrustedShareEnum

Windows NT	Yes
Win95	No
Win32s	Yes
Import Library	nddeapi.dll
Header File	nddeapi.h
Unicode	WinNT
Platform Notes	None


NDRCContextBinding

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


NDRCContextMarshall

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


NDRCContextUnmarshall

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


NDRcopy

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


NDRSContextMarshall

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


NDRSContextUnmarshall

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


NetAccessAdd

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAccessCheck

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File
Unicode	WinNT
Platform Notes	None


NetAccessDel

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAccessEnum

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAccessGetInfo

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAccessGetUserPerms

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAccessSetInfo

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetAlertRaise

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmalert.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetAlertRaiseEx

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmalert.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetApiBufferAllocate

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetApiBufferFree

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetApiBufferReallocate

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetApiBufferSize

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetapipBufferAllocate

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetAuditClear

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetAuditRead

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmapibuf.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetAuditWrite

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaudit.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


Netbios

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.dll
Header File	nb30.h
Unicode	No
Platform Notes	None


NetConfigGet

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmconfig.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetConfigGetAll

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmconfig.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetConfigSet

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmconfig.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetConnectionEnum

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetErrorLogClear

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmerrlog.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetErrorLogRead

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmerrlog.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetErrorLogWrite

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmerrlog.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetFileClose

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetFileEnum

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetFileGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGetAnyDCName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGetDCName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupAddUser

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupDelUser

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupGetUsers

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupSetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetGroupSetUsers

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupAddMember

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupDelMember

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupGetMembers

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupSetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetLocalGroupSetMembers

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetMessageBufferSend

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmmsg.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetMessageNameAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmmsg.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetMessageNameDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmmsg.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetMessageNameEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmmsg.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetMessageNameGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmmsg.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetRemoteComputerSupports

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmremutl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetRemoteTOD

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmremutl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirLock

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirSetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplExportDirUnlock

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirLock

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplImportDirUnlock

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetReplSetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmrepl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetScheduleJobAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmat.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetScheduleJobDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmat.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetScheduleJobEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmat.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetScheduleJobGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmat.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerDiskEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerGetInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.dll
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerSetInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.dll
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerTransportAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerTransportDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServerTransportEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmserver.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServiceControl

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmsvc.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServiceEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmsvc.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServiceGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmsvc.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetServiceInstall

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmsvc.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetSessionDel

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetSessionEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetSessionGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareCheck

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareDelSticky

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareEnum

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareEnumSticky

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareGetInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetShareSetInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	netapi32.dll
Header File	lmshare.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetStatisticsGet

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmstats.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUseAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmuse.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUseDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmuse.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUseEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmuse.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUseGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmuse.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserChangePassword

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	None


NetUserDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserGetGroups

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserGetLocalGroups

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserModalsGet

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserModalsSet

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserSetGroups

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetUserSetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaSetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaTransportAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaTransportDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaTransportEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaUserEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaUserGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NetWkstaUserSetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmwksta.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


NotifyBootConfigStatus

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	No
Platform Notes	None


NotifyChangeEventLog

Windows NT	New
Win95	No
Win32s	New
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ntohl

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


ntohs

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


OaBuildVersion

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


ObjectCloseAuditAlarm

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ObjectOpenAuditAlarm

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ObjectPrivilegeAuditAlarm

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OemKeyScan

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


OemToAnsi

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


OemToAnsiBuff

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


OemToChar

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


OemToCharBuff

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


OffsetClipRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


OffsetRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


OffsetRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


OffsetViewportOrgEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


OffsetWindowOrgEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


OleBuildVersion

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleConvertIStorageToOLESTREAM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleConvertIStorageToOLESTREAMEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleConvertOLESTREAMToIStorage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleConvertOLESTREAMToIStorageEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleCreate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleCreateDefaultHandler

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleCreateEmbeddingHelper

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleCreateFromData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleCreateFromFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


OleCreateLink

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleCreateLinkFromData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleCreateLinkToFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


OleCreateMenuDescriptor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleCreateStaticFromData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleDestroyMenuDescriptor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleDoAutoConvert

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleDraw

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleDuplicateData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleFlushClipboard

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleGetAutoConvert

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleGetClipboard

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleGetIconOfClass

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleGetIconOfFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


OleInitialize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleIsCurrentClipboard

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleIsRunning

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleLoad

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleLoadFromStream

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleLockRunning

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleMetafilePictFromIconAndLabel

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


OleNoteObjectVisible

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleQueryCreateFromData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleQueryLinkFromData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleRegEnumFormatEtc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleRegEnumVerbs

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleRegGetMiscStatus

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleRegGetUserType

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleRun

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleSave

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleSaveToStream

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleSetAutoConvert

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleSetClipboard

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleSetContainedObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleSetMenuDescriptor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleTranslateAccelerator

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OleUninitialize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


OpenBackupEventLog

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenClipboard

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


OpenDesktop

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


OpenEvent

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenEventLog

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


OpenFileMapping

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenIcon

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


OpenInputDesktop

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


OpenMutex

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenPrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


OpenProcess

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	On Win32s fdwAccess and fInherit ignored (set to PROCESS_ALL_ACCCESS and TRUE)


OpenProcessToken

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


OpenSCManager

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


OpenSemaphore

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


OpenService

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


OpenThreadToken

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


OpenWindowStation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


OutputDebugString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


PackDDElParam

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	dde.h
Unicode	No
Platform Notes	None


PaintDesktop

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


PaintRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PatBlt

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PathToRegion

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PeekConsoleInput

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


PeekMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


PeekNamedPipe

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


Pie

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PlayEnhMetaFile

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	no dashed widelines
Platform Notes	Windows 95: Skips records which couldn't be processed under Windows 95's GDI: greater than 16-bit coordinates


PlayEnhMetaFileRecord

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	no dashed widelines
Platform Notes	Windows 95: Skips records which couldn't be processed under Windows 95's GDI: greater than 16-bit coordinates


PlayMetaFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


PlayMetaFileRecord

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


PlaySound

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


PlgBlt

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


PolyBezier

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolyBezierTo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolyDraw

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


Polygon

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


Polyline

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolylineTo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolyPolygon

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolyPolyline

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PolyTextOut

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


PostAppMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


PostMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


PostQueuedCompletionStatus

Windows NT	Yes
Win95
Win32s
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


PostQuitMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


PostThreadMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


PrepareTape

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


PrintDlg

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.dll
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


PrinterMessageBox

Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


PrinterProperties

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


PrivilegeCheck

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


PrivilegedServiceAuditAlarm

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


PtInRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


PtInRegion

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PtVisible

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


PulseEvent

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


PurgeComm

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


QueryDosDevice

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


QueryPathOfRegTypeLib

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


QueryPerformanceCounter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


QueryPerformanceFrequency

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


QueryServiceConfig

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


QueryServiceLockStatus

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


QueryServiceObjectSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	No
Platform Notes	None


QueryServiceStatus

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	No
Platform Notes	None


RaiseException

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


RasDial

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.dll
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasEnumConnections

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.dll
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasEnumEntries

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.dll
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetConnectStatus

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.dll
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetErrorString

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.dll
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasGetProjectionInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.dll
Header File	ras.h
Unicode	WinNT
Platform Notes	None


RasHangUp

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rasapi32.dll
Header File	ras.h
Unicode	WinNT
Platform Notes	None


ReadClassStg

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


ReadClassStm

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


ReadConsole

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


ReadConsoleInput

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


ReadConsoleOutput

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


ReadConsoleOutputAttribute

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


ReadConsoleOutputCharacter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


ReadEventLog

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ReadFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	New
Platform Notes	Windows 95: No overlapped regions


ReadFileEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95 limitations


ReadFmtUserTypeStg

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


ReadPrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


ReadProcessMemory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


RealizePalette

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


Rectangle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


RectInRegion

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


RectVisible

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


recv

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


recvfrom

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


RedrawWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


RegCloseKey

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	No
Platform Notes	None


RegConnectRegistry

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegCreateKey

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegCreateKeyEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegDeleteKey

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegDeleteValue

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegEnumKey

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegEnumKeyEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegEnumValue

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegFlushKey

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	No
Platform Notes	None


RegGetKeySecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	No
Platform Notes	None


RegisterActiveObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


RegisterClass

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


RegisterClassEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


RegisterClipboardFormat

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


RegisterDialogClasses

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	scrnsave.dll
Header File	scrnsave.h
Unicode	No
Platform Notes	None


RegisterDragDrop

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


LBS_DISABLENOSCROLL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_EXTENDEDSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_HASSTRINGS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_MULTICOLUMN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_MULTIPLESEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_NODATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_NOINTEGRALHEIGHT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_NOREDRAW

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_NOTIFY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_OWNERDRAWFIXED

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_OWNERDRAWVARIABLE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_SORT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_STANDARD

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_USETABSTOPS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBS_WANTKEYBOARDINPUT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


PS_ALTERNATE

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


PS_COSMETIC

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


PS_DASH

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Doesn't support this in a wideline


PS_DASHDOT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Doesn't support this in a wideline


PS_DASHDOTDOT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Doesn't support this in a wideline


PS_DOT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Doesn't support this in a wideline


PS_ENDCAP_FLAT

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Supported only in a path


PS_ENDCAP_ROUND

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Supported only in a path


PS_ENDCAP_SQUARE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Supported only in a path


PS_GEOMETRIC

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


PS_INSIDEFRAME

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


PS_JOIN_BEVEL

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Supported only in a path


PS_JOIN_MITER

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Supported only in a path


PS_JOIN_ROUND

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Supported only in a path


PS_NULL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


PS_SOLID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


PS_USERSTYLE

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


WS_EX_ACCEPTFILES

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WS_EX_DLGMODALFRAME

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WS_EX_NOPARENTNOTIFY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WS_EX_TOPMOST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WS_EX_TRANSPARENT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


XTYP_ADVDATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_ADVREQ

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_ADVSTART

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_ADVSTOP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_CONNECT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_CONNECT_CONFIRM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_DISCONNECT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_ERROR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_EXECUTE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_MONITOR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_POKE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_REGISTER

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_REQUEST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_UNREGISTER

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_WILDCONNECT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


XTYP_XACT_COMPLETE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	ddeml.h
Unicode
Platform Notes	None


FSCTL_DISMOUNT_VOLUME

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


FSCTL_GET_COMPRESSION

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


FSCTL_LOCK_VOLUME

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


FSCTL_UNLOCK_VOLUME

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_CHECK_VERIFY

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_EJECT_MEDIA

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_FORMAT_TRACKS

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_GET_DRIVE_GEOMETRY

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_GET_DRIVE_LAYOUT

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_GET_MEDIA_TYPES

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_GET_PARTITION_INFO

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_LOAD_MEDIA

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_MEDIA_REMOVAL

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_PERFORMANCE

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_REASSIGN_BLOCKS

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_SET_DRIVE_LAYOUT

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_SET_PARTITION_INFO

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_DISK_VERIFY

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


IOCTL_SERIAL_LSRMST_INSERT

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode	No
Platform Notes	None


ACL_INFORMATION_CLASS

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winnt.h
Unicode
Platform Notes	None


MEDIA_TYPE

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winioctl.h
Unicode
Platform Notes	None


RASCONNSTATE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ras.h
Unicode
Platform Notes	None


RASPROJECTION

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	ras.h
Unicode
Platform Notes	None


SECURITY_IMPERSONATION_LEVEL

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winnt.h
Unicode
Platform Notes	None


SID_NAME_USE

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winnt.h
Unicode
Platform Notes	None


TOKEN_INFORMATION_CLASS

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winnt.h
Unicode
Platform Notes	None


TOKEN_TYPE

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winnt.h
Unicode
Platform Notes	None


__WSAFDIsSet

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.lib
Header File	winsock.h
Unicode	No
Platform Notes	None


_hread

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_hwrite

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_lclose

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_lcreat

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_llseek

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_lopen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_lread

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


_lwrite

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AbnormalTermination

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


AbortDoc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


AbortPath

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.lib
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


AbortPrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.lib
Header File	wingdi.h
Unicode	No
Platform Notes	None


AbortSystemShutdown

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


accept

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.lib
Header File	winsock.h
Unicode	No
Platform Notes	None


AccessCheck

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	No
Platform Notes	None


AccessCheckAndAuditAlarm

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.lib
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


acmDriverAdd

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmDriverClose

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverDetails

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmDriverEnum

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverID

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverMessage

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverOpen

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverPriority

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmDriverRemove

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmFilterChoose

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFilterDetails

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFilterEnum

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFilterTagDetails

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFilterTagEnum

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatChoose

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatDetails

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatEnum

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatSuggest

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmFormatTagDetails

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmFormatTagEnum

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	WinNT
Platform Notes	None


acmGetVersion

Windows NT	New
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmMetrics

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamClose

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.lib
Header File	msacm.h
Unicode	No
Platform Notes	None


RegisterEventSource

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


RegisterHotKey

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


RegisterServiceCtrlHandler

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


RegisterTypeLib

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


RegisterWindowMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


RegLoadKey

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegNotifyChangeKeyValue

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	No
Platform Notes	None


RegOpenKey

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegOpenKeyEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegQueryInfoKey

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegQueryValue

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegQueryValueEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegReplaceKey

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegRestoreKey

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegSaveKey

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegSetKeySecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winreg.h
Unicode	No
Platform Notes	None


RegSetValue

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegSetValueEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


RegUnLoadKey

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	advapi32.dll
Header File	winreg.h
Unicode	WinNT
Platform Notes	None


ReleaseCapture

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ReleaseDC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ReleaseMutex

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ReleaseSemaphore

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ReleaseStgMedium

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


RemoveDirectory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


RemoveFontResource

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


RemoveMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


RemoveProp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ReplaceText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.dll
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


ReplyMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ReportEvent

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ResetDC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


ResetDisplay

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ResetEvent

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ResetPrinter

Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


ResizePalette

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


RestoreDC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


ResumeThread

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ReuseDDElParam

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	dde.h
Unicode	No
Platform Notes	None


RevertToSelf

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


RevokeActiveObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


RevokeDragDrop

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


RoundRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


RpcAbnormalTermination

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcBindingCopy

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcBindingFree

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcBindingFromStringBinding

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingInqAuthClient

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcBindingInqAuthInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingInqObject

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcBindingReset

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcBindingServerFromClient

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcBindingSetAuthInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcBindingSetObject

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcBindingToStringBinding

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcBindingVectorFree

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcCancelThread

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcEndExcept

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcEndFinally

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcEpRegister

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcEpRegisterNoReplace

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcEpResolveBinding

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcEpUnregister

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcExcept

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcExceptionCode

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcFinally

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcIfIdVectorFree

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcIfInqId

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcImpersonateClient

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpc.h
Unicode
Platform Notes	None


RpcMgmtEnableIdleCleanup

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtEpEltInqBegin

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtEpEltInqDone

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtEpEltInqNext

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtEpUnregister

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtInqComTimeout

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtInqDefaultProtectLevel

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtInqIfIds

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtInqServerPrincName

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcMgmtInqStats

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtIsServerListening

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtSetAuthorizationFn

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtSetCancelTimeout

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtSetComTimeout

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtSetServerStackSize

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtStatsVectorFree

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtStopServerListening

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcMgmtWaitServerListen

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcNetworkInqProtseqs

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcNetworkIsProtseqValid

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingExport

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingImportBegin

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingImportDone

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsBindingImportNext

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsBindingInqEntryName

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingLookupBegin

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsBindingLookupDone

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsBindingLookupNext

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsBindingSelect

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsBindingUnexport

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsEntryExpandName

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsEntryObjectInqBegin

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsEntryObjectInqDone

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsEntryObjectInqNext

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsGroupDelete

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsGroupMbrAdd

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsGroupMbrInqBegin

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsGroupMbrInqDone

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsGroupMbrInqNext

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsGroupMbrRemove

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtBindingUnexport

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtEntryCreate

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtEntryDelete

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtEntryInqIfIds

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsMgmtHandleSetExpAge

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsMgmtInqExpAge

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsMgmtSetExpAge

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsProfileDelete

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsProfileEltAdd

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsProfileEltInqBegin

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsProfileEltInqDone

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	No
Platform Notes	None


RpcNsProfileEltInqNext

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcNsProfileEltRemove

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcns4.dll
Header File	rpcnsi.h
Unicode	WinNT
Platform Notes	None


RpcObjectInqType

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcObjectSetInqFn

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcObjectSetType

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


RpcProtseqVectorFree

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcRaiseException

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcRevertToSelf

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpc.h
Unicode
Platform Notes	None


RpcServerInqBindings

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcServerInqIf

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcServerListen

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcServerRegisterAuthInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcServerRegisterIf

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcServerUnregisterIf

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcServerUseAllProtseqs

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcServerUseAllProtseqsIf

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcServerUseProtseq

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcServerUseProtseqEp

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcServerUseProtseqIf

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode
Platform Notes	None


RpcSmAllocate

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSmClientFree

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSmDestroyClientContext

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSmDisableAllocate

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSmEnableAllocate

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSmFree

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSmGetThreadHandle

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSmSetClientAllocFree

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSmSetThreadHandle

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSmSwapClientAllocFree

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSsAllocate

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSsDestroyClientContext

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSsDisableAllocate

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSsEnableAllocate

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSsFree

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSsGetThreadHandle

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSsSetClientAllocFree

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSsSetThreadHandle

Windows NT	Yes
Win95
Win32s
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcSsSwapClientAllocFree

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode	No
Platform Notes	None


RpcStringBindingCompose

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcStringBindingParse

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcStringFree

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcTestCancel

Windows NT	Yes
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


RpcTryExcept

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RpcTryFinally

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	rpc.h
Unicode	No
Platform Notes	None


RxNetAccessAdd

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxNetAccessDel

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxNetAccessEnum

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxNetAccessGetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxNetAccessGetUserPerms

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxNetAccessSetInfo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmaccess.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


RxRemoteApi

Windows NT	Yes
Win95	No
Win32s	No
Import Library	netapi32.dll
Header File	lmremutl.h
Unicode	WinNT
Platform Notes	All LanMan APIs are UNICODE only


SafeArrayAccessData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayAllocData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayAllocDescriptor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayCopy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayCreate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayDestroy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayDestroyData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayDestroyDescriptor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayGetDim

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayGetElement

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayGetElemsize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayGetLBound

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayGetUBound

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayLock

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayPtrOfIndex

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayPutElement

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayRedim

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayUnaccessData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SafeArrayUnlock

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SaveDC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


ScaleViewportExtEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ScaleWindowExtEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ScheduleJob

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


ScreenSaverConfigureDialog

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	scrnsave.dll
Header File	scrnsave.h
Unicode	No
Platform Notes	None


ScreenSaverProc

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	scrnsave.dll
Header File	scrnsave.h
Unicode	No
Platform Notes	None


ScreenToClient

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ScrollConsoleScreenBuffer

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


ScrollDC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ScrollWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ScrollWindowEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SearchPath

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


select

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


SelectClipPath

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SelectClipRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SelectObject

Windows NT	New
Win95	Yes
Win32s	New
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes


SelectPalette

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


send

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


SendDlgItemMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SendMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SendMessageCallback

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	Windows 95: wParam is 16-bits


SendMessageTimeout

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	Windows 95: wParam is 16-bits


SendNotifyMessage

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	Windows 95: wParam is 16-bits


sendto

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


ServiceMain

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File
Unicode	No
Platform Notes	None


SetAbortProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetAclInformation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetActiveWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetArcDirection

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetBitmapBits

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetBitmapDimensionEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetBkColor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetBkMode

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetBoundsRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetBrushOrgEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetCapture

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetCaretBlinkTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetCaretPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetClassLong

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetClassWord

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetClipboardData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetClipboardViewer

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetColorAdjustment

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetColorSpace

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetCommBreak

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetCommConfig

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetCommMask

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetCommState

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetCommTimeouts

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetComputerName

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetConsoleActiveScreenBuffer

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleCP

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleCtrlHandler

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleCursorInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleCursorPosition

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleMode

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleOutputCP

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleScreenBufferSize

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleTextAttribute

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConsoleTitle

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


SetConsoleWindowInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


SetConvertStg

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


SetCurrentDirectory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetCursor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetCursorPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetDebugErrorLevel

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetDefaultCommConfig

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetDeviceGammaRamp

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetDIBColorTable

Windows NT	New
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetDIBits

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetDIBitsToDevice

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetDlgItemInt

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetDlgItemText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetDoubleClickTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetEndOfFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetEnhMetaFileBits

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetEnvironmentVariable

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetErrorInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


SetErrorMode

Windows NT	New
Win95	Yes
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	This is used for RISC platforms only. x86 platforms and Windows 95 return a constant


SetEvent

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetFileApisToANSI

Windows NT	Yes
Win95
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	On Win32s all file APIs are ANSI


SetFileApisToOEM

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	On Win32s the file APIs are always OEM


SetFileAttributes

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetFilePointer

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetFileSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetFileTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetFocus

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetForegroundWindow

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetForm

Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


SetGraphicsMode

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Only GM_COMPATIBLE is supported


SetHandleCount

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetHandleInformation

Windows NT	Yes
Win95
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetICMMode

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetICMProfile

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


SetJob

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


SetKernelObjectSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetKeyboardState

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetLastError

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetLastErrorEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetLocaleInfo

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


SetLocalTime

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetMailslotInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetMapMode

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetMapperFlags

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMenuContextHelpId

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMenuDefaultItem

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMenuItemBitmaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMenuItemInfo

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMessageExtraInfo

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMessageQueue

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetMetaFileBitsEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetMetaRgn

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetMiterLimit

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetNamedPipeHandleState

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetPaletteEntries

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetParent

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetPixel

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetPixelFormat

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetPixelV

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetPolyFillMode

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetPrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


SetPrinterData

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


SetPriorityClass

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetPrivateObjectSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetProcessShutdownParameters

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetProcessWindowStation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetProcessWorkingSetSize

Windows NT	Yes
Win95
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetProp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetRectEmpty

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetRectRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetROP2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetScrollInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetScrollPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetScrollRange

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetSecurityDescriptorDacl

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSecurityDescriptorGroup

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSecurityDescriptorOwner

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSecurityDescriptorSacl

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetService

Windows NT	Yes
Win95
Win32s	No
Import Library	wsock32.dll
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


SetServiceBits

Windows NT	New
Win95	No
Win32s	New
Import Library	advapi32.dll
Header File	lmserver.h
Unicode	No
Platform Notes	None


SetServiceObjectSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	No
Platform Notes	None


SetServiceStatus

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	No
Platform Notes	None


setsockopt

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


SetStdHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetStretchBltMode

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetSwapAreaSize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSysColors

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetSysModalWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


SetSystemCursor

Windows NT	New
Win95	Yes
Win32s	New
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetSystemPaletteUse

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetSystemPowerState

Windows NT
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSystemTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetSystemTimeAdjustment

Windows NT	New
Win95	No
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetTapeParameters

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetTapePosition

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetTextAlign

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetTextCharacterExtra

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetTextColor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetTextJustification

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


SetThreadAffinityMask

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	This is valid on SMP platforms only; Windows 95 returns a constant


SetThreadContext

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetThreadDesktop

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: NOP; only one desktop


SetThreadLocale

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	Windows 95: Locales are static & can change only at system boot


SetThreadPriority

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetThreadToken

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetTimer

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetTimeZoneInformation

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetTokenInformation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetUnhandledExceptionFilter

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetupComm

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SetUserObjectInformation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetUserObjectSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetViewportExtEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetViewportOrgEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetVolumeLabel

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


SetWindowContextHelpId

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetWindowExtEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetWindowLong

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetWindowOrgEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SetWindowPlacement

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetWindowPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetWindowRgn

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetWindowsHook

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetWindowsHookEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetWindowText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SetWindowWord

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SetWinMetaFileBits

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


SetWorldTransform

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


ShellAbout

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.dll
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


ShellExecute

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.dll
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


short_array_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


short_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


short_from_ndr_temp

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


ShowCaret

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ShowCursor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ShowHideMenuCtl

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


ShowOwnedPopups

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ShowScrollBar

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ShowWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ShowWindowAsync

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


shutdown

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


SizeofResource

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


Sleep

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SleepEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


sndPlaySound

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


socket

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


StartDoc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


StartDocPrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


StartPage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


StartPagePrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


StartService

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


StartServiceCtrlDispatcher

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


StgCreateDocfile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


StgCreateDocfileOnILockBytes

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


StgIsStorageFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


StgIsStorageILockBytes

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


StgOpenStorage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


StgOpenStorageOnILockBytes

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


StgSetTimes

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


StretchBlt

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


StretchDIBits

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


StringFromCLSID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


StringFromGUID2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


StringFromIID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


StrokeAndFillPath

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


StrokePath

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


SubtractRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SuspendThread

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SwapBuffers

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


SwapMouseButton

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SwitchDesktop

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


SysAllocString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysAllocStringByteLen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysAllocStringLen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysFreeString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysReAllocString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysReAllocStringLen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysStringByteLen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SysStringLen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


SystemParametersInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


SystemTimeToFileTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


SystemTimeToTzSpecificLocalTime

Windows NT	New
Win95	No
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


TabbedTextOut

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


TerminateProcess

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


TerminateThread

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


TextOut

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: 16-bit coordinates only


TileWindows

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


timeBeginPeriod

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeEndPeriod

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeGetDevCaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeGetSystemTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeGetTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeKillEvent

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


timeSetEvent

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


TlsAlloc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


TlsFree

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


TlsGetValue

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


TlsSetValue

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ToAscii

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ToAsciiEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ToUnicode

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


TrackPopupMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


TrackPopupMenuEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


TransactNamedPipe

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


TranslateAccelerator

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


TranslateCharsetInfo

Windows NT
Win95	Yes
Win32s
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


TranslateMDISysAccel

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


TranslateMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


TransmitCommChar

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


TransmitFile

Windows NT	Yes
Win95
Win32s	No
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


tree_into_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


tree_peek_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


tree_size_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


UInt32x32To64

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


UnhandledExceptionFilter

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


UnhookWindowsHook

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


UnhookWindowsHookEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


UnionRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


UnloadKeyboardLayout

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: Only 1 keybrd loaded at once


UnlockFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


UnlockFileEx

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


UnlockResource

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


UnlockSegment

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


UnlockServiceDatabase

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	No
Platform Notes	None


UnmapViewOfFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


UnpackDDElParam

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	dde.h
Unicode	No
Platform Notes	None


UnrealizeObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


UnregisterClass

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


UnregisterHotKey

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


UpdateColors

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


UpdateResource

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


UpdateWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


UuidCompare

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


UuidCreate

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


UuidCreateNil

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


UuidEqual

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


UuidFromString

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


UuidHash

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


UuidIsNil

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	No
Platform Notes	None


UuidToString

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


ValidateRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ValidateRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


VarBoolFromCy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromDate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromDisp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromI2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromI4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromR4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromR8

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBoolFromStr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBoolFromUI1

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarBstrFromBool

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromCy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromDate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromDisp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromI2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromI4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromR4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromR8

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarBstrFromUI1

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarCyFromBool

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromDate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromDisp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromI2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromI4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromR4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromR8

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarCyFromStr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarCyFromUI1

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromBool

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromCy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromDisp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromI2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromI4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromR4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromR8

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarDateFromStr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarDateFromUI1

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromBool

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromCy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromDate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromDisp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromI4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromR4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromR8

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI2FromStr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarI2FromUI1

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromBool

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromCy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromDate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromDisp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromI2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromR4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromR8

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarI4FromStr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarI4FromUI1

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantChangeType

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantChangeTypeEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantClear

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantCopy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantCopyInd

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantInit

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VariantTimeToDosDateTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromBool

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromCy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromDate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromDisp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromI2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromI4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromR8

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR4FromStr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VarR4FromUI1

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromBool

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromCy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromDate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromDisp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromI2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromI4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromR4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromStr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarR8FromUI1

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromBool

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromCy

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromDate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromDisp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromI2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromI4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromR4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromR8

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


VarUI1FromStr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


VerFindFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	version.dll
Header File	winver.h
Unicode	WinNT
Platform Notes	None


VerInstallFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	version.dll
Header File	winver.h
Unicode	WinNT
Platform Notes	None


VerLanguageName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winver.h
Unicode	WinNT
Platform Notes	None


VerQueryValue

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	version.dll
Header File	winver.h
Unicode	WinNT
Platform Notes	None


VideoForWindowsVersion

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


VirtualAlloc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualFree

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualLock

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualProtect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualProtectEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualQuery

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualQueryEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


VirtualUnlock

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


VkKeyScan

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


VkKeyScanEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


WaitCommEvent

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitForDebugEvent

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitForInputIdle

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


WaitForMultipleObjects

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitForMultipleObjectsEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitForPrinterChange

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: PRINTER_CHANGE_FORM is not supported


WaitForSingleObject

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitForSingleObjectEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


WaitMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


WaitNamedPipe

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


waveInAddBuffer

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInClose

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInGetDevCaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


waveInGetErrorText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


waveInGetID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInGetNumDevs

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInGetPosition

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInOpen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInPrepareHeader

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInReset

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInStart

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInStop

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveInUnprepareHeader

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutBreakLoop

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutClose

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetDevCaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


waveOutGetErrorText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


waveOutGetID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetNumDevs

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetPitch

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetPlaybackRate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetPosition

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutGetVolume

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutOpen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutPause

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutPrepareHeader

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutReset

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutRestart

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutSetPitch

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutSetPlaybackRate

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutSetVolume

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutUnprepareHeader

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


waveOutWrite

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


wglCreateContext

Windows NT	New
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


wglDeleteContext

Windows NT	New
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


wglGetCurrentContext

Windows NT	New
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


wglGetCurrentDC

Windows NT	New
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


wglGetProcAddress

Windows NT	New
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


wglMakeCurrent

Windows NT	New
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


wglMakeShareLists

Windows NT	New
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


wglUseFontBitmaps

Windows NT	New
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


wglUseFontOutlines

Windows NT	New
Win95	No
Win32s	No
Import Library	opengl32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


WideCharToMultiByte

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


WidenPath

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


WindowFromDC

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


WindowFromPoint

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


WinExec

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


WinHelp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


WinMain

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


WNetAddConnection

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetAddConnection2

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetAddConnection3

Windows NT	Yes
Win95
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetCancelConnection

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetCancelConnection2

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetCloseEnum

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	No
Platform Notes	None


WNetConnectionDialog

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	No
Platform Notes	None


WNetDisconnectDialog

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	No
Platform Notes	None


WNetEnumResource

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetGetConnection

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetGetLastError

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetGetUniversalName

Windows NT	Yes
Win95
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetGetUser

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WNetOpenEnum

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	mpr.dll
Header File	winnetwk.h
Unicode	WinNT
Platform Notes	None


WriteClassStg

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


WriteClassStm

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


WriteConsole

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


WriteConsoleInput

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


WriteConsoleOutput

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


WriteConsoleOutputAttribute

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


WriteConsoleOutputCharacter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


WriteFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	New
Platform Notes	Windows 95: No overlapped regions


WriteFileEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95 limitations


WriteFmtUserTypeStg

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


WritePrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


WritePrivateProfileSection

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WritePrivateProfileString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WritePrivateProfileStruct

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WriteProcessMemory

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


WriteProfileSection

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WriteProfileString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


WriteTapemark

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


WSAAsyncGetHostByAddr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSAAsyncGetHostByName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSAAsyncGetProtoByName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSAAsyncGetProtoByNumber

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSAAsyncGetServByName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSAAsyncGetServByPort

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSAAsyncSelect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSACancelAsyncRequest

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSACancelBlockingCall

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSACleanup

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSAGetLastError

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSAIsBlocking

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSARecvEx

Windows NT	Yes
Win95
Win32s	No
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSASetBlockingHook

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSASetLastError

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSAStartup

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


WSAUnhookBlockingHook

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


wsprintf

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


wvsprintf

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ZeroMemory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


IAVIEditStream::Clone

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIEditStream::Copy

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIEditStream::Cut

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIEditStream::Paste

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIEditStream::SetInfo

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIFile::CreateStream

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIFile::EndRecord

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIFile::GetStream

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIFile::Info

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIFile::Open

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIFile::ReadData

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIFile::WriteData

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStream::Create

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStream::Delete

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStream::FindSample

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStream::Info

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStream::Read

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStream::ReadData

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStream::ReadFormat

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStream::SetFormat

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStream::Write

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStream::WriteData

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStreaming::Begin

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IAVIStreaming::End

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h; aviiface.h
Unicode
Platform Notes	None


IGetFrame::Begin

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h
Unicode
Platform Notes	None


IGetFrame::End

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h
Unicode
Platform Notes	None


IGetFrame::GetFrame

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h
Unicode
Platform Notes	None


IGetFrame::SetFormat

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h
Unicode
Platform Notes	None


Animate_Close

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


Animate_Create

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


Animate_Open

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


Animate_Play

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


Animate_Seek

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


Animate_Stop

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


AVIStreamDataSize

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamEnd

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamEndTime

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamFormatSize

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamIsKeyFrame

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamLengthTime

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamNearestKeyFrame

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamNearestKeyFrameTime

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamNearestSample

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamNearestSampleTime

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamNextKeyFrame

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamNextKeyFrameTime

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamNextSample

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamNextSampleTime

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamPrevKeyFrame

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamPrevKeyFrameTime

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamPrevSample

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamPrevSampleTime

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamSampleSize

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamSampleToSample

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


AVIStreamStartTime

Windows NT
Win95	Yes
Win32s
Import Library
Header File	vfw.h/avifile.h
Unicode
Platform Notes	None


CMYK

Windows NT
Win95	Yes
Win32s
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


DrawDibUpdate

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


FORWARD_WM_NOTIFY

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


GetBValue

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetCValue

Windows NT
Win95	Yes
Win32s
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetGValue

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetKValue

Windows NT
Win95	Yes
Win32s
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetMValue

Windows NT
Win95	Yes
Win32s
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetRValue

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetYValue

Windows NT
Win95	Yes
Win32s
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


HANDLE_WM_NOTIFY

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


HIBYTE

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


HIWORD

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


ICAbout

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressBegin

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressEnd

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressGetFormat

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressGetFormatSize

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressGetSize

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICCompressQuery

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICConfigure

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressBegin

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressEnd

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressGetFormat

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressGetFormatSize

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressGetPalette

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressOpen

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDecompressQuery

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawEnd

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawFlush

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawGetTime

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawOpen

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawQuery

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawRealize

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawSetTime

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawStart

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawStartPlay

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawStop

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawStopPlay

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICDrawWindow

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetBuffersWanted

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetDefaultKeyFrameRate

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetDefaultQuality

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetState

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICGetStateSize

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICQueryAbout

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


ICQueryConfigure

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	vfw.h
Unicode	No
Platform Notes	None


INDEXTOOVERLAYMASK

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


INDEXTOSTATEIMAGEMASK

Windows NT	New
Win95	Yes
Win32s	No
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


LANGIDFROMLCID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


LOBYTE

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


LOWORD

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


MAKEINTATOM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


MAKEINTRESOURCE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


MAKELANGID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


MAKELCID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


MAKELONG

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


MAKELPARAM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


MAKELRESULT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


MAKEPOINTS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


MAKEROP4

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


MAKEWORD

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


MAKEWPARAM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


max

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	windef.h
Unicode	No
Platform Notes	None


MCI_HMS_HOUR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_HMS_MINUTE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_HMS_SECOND

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MAKE_HMS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MAKE_MSF

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MAKE_TMSF

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MSF_FRAME

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MSF_MINUTE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_MSF_SECOND

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_TMSF_FRAME

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_TMSF_MINUTE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_TMSF_SECOND

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_TMSF_TRACK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCIWndCanConfig

Windows NT
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


MCIWndCanEject

Windows NT
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


MCIWndCanPlay

Windows NT
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


MCIWndCanRecord

Windows NT
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


MCIWndCanSave

Windows NT
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


MEVT_EVENTPARM

Windows NT
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


MEVT_EVENTTYPE

Windows NT
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


min

Windows NT
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


mmioFOURCC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


PALETTEINDEX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


PALETTERGB

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


POINTSTOPOINT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


POINTTOPOINTS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


PRIMARYLANGID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


RGB

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	wingdi.h
Unicode	No
Platform Notes	None


SORTIDFROMLCID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


SUBLANGID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winnt.h
Unicode	No
Platform Notes	None


TEXT

Windows NT
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


BM_CLICK

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_GETCHECK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_GETSTATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_SETCHECK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_SETSTATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BM_SETSTYLE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_CLICKED

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_DBLCLK

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_DISABLE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_DOUBLECLICKED

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_HILITE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_PAINT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_PUSHED

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_UNHILITE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


BN_UNPUSHED

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_ADDSTRING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_DELETESTRING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_DIR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_FINDSTRING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_FINDSTRINGEXACT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETCOUNT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETCURSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETDROPPEDCONTROLRECT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETDROPPEDSTATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETDROPPEDWIDTH

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETEDITSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETEXTENDEDUI

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETHORIZONTALEXTENT

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETITEMDATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETITEMHEIGHT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETLBTEXT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETLBTEXTLEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETLOCALE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_GETTOPINDEX

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_INITSTORAGE

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_INSERTSTRING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_LIMITTEXT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_MSGMAX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_RESETCONTENT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SELECTSTRING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETCURSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETDROPPEDWIDTH

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETEDITSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETEXTENDEDUI

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETHORIZONTALEXTENT

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETITEMDATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETITEMHEIGHT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETLOCALE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SETTOPINDEX

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CB_SHOWDROPDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_CLOSEUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_DBLCLK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_DROPDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_EDITCHANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_EDITUPDATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_ERRSPACE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_KILLFOCUS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_SELCHANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_SELENDCANCEL

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_SELENDOK

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBN_SETFOCUS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_LOWERCASE

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CBS_UPPERCASE

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CPL_DBLCLK

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_EXIT

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_GETCOUNT

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_INIT

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_INQUIRE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_NEWINQUIRE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_SELECT

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


CPL_STOP

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


DM_GETDEFID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


DM_REPOSITION

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


DM_SETDEFID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_CANUNDO

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_CHARFROMPOS

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_EMPTYUNDOBUFFER

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_FMTLINES

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETFIRSTVISIBLELINE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	For Single Line Edit controls Win32s returns 0


EM_GETHANDLE

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETLIMITTEXT

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETLINE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETLINECOUNT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETMARGINS

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETMODIFY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETPASSWORDCHAR

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETRECT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETTHUMB

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_GETWORDBREAKPROC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_LIMITTEXT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_LINEFROMCHAR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_LINEINDEX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_LINELENGTH

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_LINESCROLL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_POSFROMCHAR

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_REPLACESEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SCROLL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SCROLLCARET

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETHANDLE

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETLIMITTEXT

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETMARGINS

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETMODIFY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETPASSWORDCHAR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETREADONLY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETRECT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETRECTNP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETTABSTOPS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETWORDBREAK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_SETWORDBREAKPROC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EM_UNDO

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_CHANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_ERRSPACE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_HSCROLL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_KILLFOCUS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_MAXTEXT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_SETFOCUS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_UPDATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EN_VSCROLL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


FM_GETDRIVEINFO

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	WinNT
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_GETFILESEL

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	WinNT
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_GETFILESELLFN

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	WinNT
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_GETFOCUS

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_GETSELCOUNT

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_GETSELCOUNTLFN

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_REFRESH_WINDOWS

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FM_RELOAD_EXTENSIONS

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_HELPMENUITEM

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_HELPSTRING

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_INITMENU

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_LOAD

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_SELCHANGE

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_TOOLBARLOAD

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_UNLOAD

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


FMEVENT_USER_REFRESH

Windows NT	Yes
Win95	No
Win32s	No
Import Library
Header File	wfext.h
Unicode	No
Platform Notes	Windows 95: Only supports 16-bit FileManager


LB_ADDFILE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_ADDSTRING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_DELETESTRING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_DIR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_FINDSTRING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_FINDSTRINGEXACT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETANCHORINDEX

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETCARETINDEX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETCOUNT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETCURSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETHORIZONTALEXTENT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETITEMDATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETITEMHEIGHT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETITEMRECT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETLOCALE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETSELCOUNT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_GETSELITEMS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETTEXT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETTEXTLEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_GETTOPINDEX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_INITSTORAGE

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_INSERTSTRING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_ITEMFROMPOINT

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_MSGMAX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_RESETCONTENT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SELECTSTRING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SELITEMRANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SELITEMRANGEEX

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETANCHORINDEX

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETCARETINDEX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SETCOLUMNWIDTH

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETCOUNT

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETCURSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SETHORIZONTALEXTENT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETITEMDATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SETITEMHEIGHT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SETLOCALE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETSEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LB_SETTABSTOPS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LB_SETTOPINDEX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: wParam is 16-bits


LBN_DBLCLK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBN_ERRSPACE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBN_KILLFOCUS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBN_SELCANCEL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBN_SELCHANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LBN_SETFOCUS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


MCI_BREAK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_CLOSE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_COPY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_CUE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_CUT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_DELETE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_ESCAPE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_FREEZE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_GETDEVCAPS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_INFO

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_LOAD

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_OPEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_PASTE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_PAUSE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_PLAY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_PUT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_REALIZE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_RECORD

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_RESUME

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SAVE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SEEK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SET

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SPIN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_STATUS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_STEP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_STOP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_SYSINFO

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_UNFREEZE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_UPDATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_WHERE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MCI_WINDOW

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_CLOSE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_DATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_ERROR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_LONGDATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_LONGERROR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MIM_OPEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY1BUTTONDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY1BUTTONUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY1MOVE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY1ZMOVE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY2BUTTONDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY2BUTTONUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY2MOVE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_JOY2ZMOVE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MCINOTIFY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_CLOSE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_DATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_ERROR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_LONGDATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_LONGERROR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MIM_OPEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MOM_CLOSE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MOM_DONE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_MOM_OPEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WIM_CLOSE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WIM_DATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WIM_OPEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WOM_CLOSE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WOM_DONE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MM_WOM_OPEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_CLOSE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_OPEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_READ

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_SEEK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_WRITE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MMIOM_WRITEFLUSH

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MOM_CLOSE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MOM_DONE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


MOM_OPEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


NM_CLICK

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


NM_DBLCLK

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


NM_KILLFOCUS

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


NM_OUTOFMEMORY

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


NM_RCLICK

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


NM_RDBLCLK

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


NM_RETURN

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


NM_SETFOCUS

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_ENABLE_ARROWS

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_GETPOS

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_GETRANGE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_GETSCROLLINFO

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_SETPOS

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_SETRANGE

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_SETRANGEREDRAW

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


SBM_SETSCROLLINFO

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


STM_GETICON

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


STM_MSGMAX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


STM_SETICON

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


STN_CLICKED

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


STN_DBLCLICKED

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	winuser.h
Unicode
Platform Notes	None


STN_DBLCLK

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


STN_DISABLE

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	winuser.h
Unicode
Platform Notes	None


STN_ENABLE

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	winuser.h
Unicode
Platform Notes	None


WM_ACTIVATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ACTIVATEAPP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_APP

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ASKCBFORMATNAME

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


acmStreamConvert

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.dll
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamOpen

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.dll
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamPrepareHeader

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.dll
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamReset

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.dll
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamSize

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.dll
Header File	msacm.h
Unicode	No
Platform Notes	None


acmStreamUnprepareHeader

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	msacm32.dll
Header File	msacm.h
Unicode	No
Platform Notes	None


AcsLan

Windows NT	Yes
Win95	No
Win32s	No
Import Library	dlcapi.dll
Header File	dlcapi.h
Unicode	No
Platform Notes	None


ActivateKeyboardLayout

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	Windows 95: Only 1 keybrd loaded at once


AddAccessAllowedAce

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


AddAccessDeniedAce

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


AddAce

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


AddAtom

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


AddAuditAccessAce

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


AddFontResource

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


AddForm

Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddJob

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddMonitor

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPort

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPrinterDriver

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPrintProcessor

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AddPrintProvidor

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AdjustTokenGroups

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


AdjustTokenPrivileges

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


AdjustWindowRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


AdjustWindowRectEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


AdvancedDocumentProperties

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


AllocateAndInitializeSid

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


AllocateLocallyUniqueId

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


AllocConsole

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


AngleArc

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


AnimatePalette

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


AnsiLower

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


AnsiLowerBuff

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


AnsiNext

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


AnsiPrev

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


AnsiToOem

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


AnsiToOemBuff

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


AnsiUpper

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


AnsiUpperBuff

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


AnyPopup

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


AppendMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


Arc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ArcTo

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


AreAllAccessesGranted

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


AreAnyAccessesGranted

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


AreFileApisANSI

Windows NT	New
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	On Win32s the file APIs are always ANSI


ArrangeIconicWindows

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


AttachThreadInput

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


auxGetDevCaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	WinNT
Platform Notes	None


auxGetNumDevs

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


auxGetVolume

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


auxOutMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


auxSetVolume

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


AVIBuildFilter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIClearClipboard

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileAddRef

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileCreateStream

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileEndRecord

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileExit

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileGetStream

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIFileInit

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileOpen

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIFileReadData

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileRelease

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIFileWriteData

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIGetFromClipboard

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIMakeCompressedStream

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIMakeFileFromStreams

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIMakeStreamFromClipboard

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIPutFileOnClipboard

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVISave

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVISaveOptions

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVISaveOptionsFree

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVISaveV

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIStreamAddRef

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamBeginStreaming

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamCreate

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamEndStreaming

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamFindSample

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamGetFrame

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamGetFrameClose

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamGetFrameOpen

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIStreamLength

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamOpenFromFile

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


AVIStreamRead

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamReadData

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamReadFormat

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamRelease

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamSampleToTime

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamSetFormat

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamStart

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamTimeToSample

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamWrite

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


AVIStreamWriteData

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


BackupEventLog

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


BackupRead

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


BackupSeek

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


BackupWrite

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


Beep

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


BeginDeferWindowPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


BeginPaint

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


BeginPath

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


BeginUpdateResource

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


bind

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


BindMoniker

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


BitBlt

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


BringWindowToTop

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


BroadcastSystemMessage

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


BuildCommDCB

Windows NT	New
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


BuildCommDCBAndTimeouts

Windows NT	New
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CallMsgFilter

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CallNamedPipe

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CallNextHookEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CallWindowProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CancelDC

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


capCreateCaptureWindow

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


capGetDriverDescription

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


CascadeWindows

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CANCELJOURNAL

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CANCELMODE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CAPTURECHANGED

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CHANGECBCHAIN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CHAR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CHARTOITEM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CHILDACTIVATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CHOOSEFONT_GETLOGFONT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	commdlg.h
Unicode	No
Platform Notes	None


WM_CLEAR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CLOSE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_COMMAND

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_COMMNOTIFY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_COMPACTING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_COMPAREITEM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CONTEXTMENU

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_COPY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_COPYDATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CPL_LAUNCH

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


WM_CPL_LAUNCHED

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	cpl.h
Unicode	No
Platform Notes	None


WM_CREATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORBTN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORDLG

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLOREDIT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORLISTBOX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORMSGBOX

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORSCROLLBAR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CTLCOLORSTATIC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_CUT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DDE_ACK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_ADVISE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_DATA

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_EXECUTE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_FIRST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_INITIATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_LAST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_POKE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_REQUEST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_TERMINATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DDE_UNADVISE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	dde.h
Unicode	No
Platform Notes	None


WM_DEADCHAR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DELETEITEM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DESTROY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DESTROYCLIPBOARD

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DEVMODECHANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DISPLAYCHANGE

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DRAWCLIPBOARD

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DRAWITEM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_DROPFILES

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ENABLE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ENDSESSION

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ENTERIDLE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ENTERMENULOOP

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ERASEBKGND

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_EXITMENULOOP

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_FONTCHANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETDLGCODE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETFONT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETHOTKEY

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETICON

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETMINMAXINFO

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETTEXT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_GETTEXTLENGTH

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_HELP

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_HOTKEY

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_HSCROLL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_HSCROLLCLIPBOARD

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_ICONERASEBKGND

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_INITDIALOG

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_INITMENU

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_INITMENUPOPUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_KEYDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_KEYFIRST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_KEYLAST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_KEYUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_KILLFOCUS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_LBUTTONDBLCLK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_LBUTTONDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_LBUTTONUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MBUTTONDBLCLK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MBUTTONDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MBUTTONUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIACTIVATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDICASCADE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDICREATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIDESTROY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIGETACTIVE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIICONARRANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIMAXIMIZE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDINEXT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIREFRESHMENU

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDIRESTORE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDISETMENU

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MDITILE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MEASUREITEM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MENUCHAR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MENUSELECT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MOUSEACTIVATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MOUSEFIRST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MOUSELAST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MOUSEMOVE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MOVE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_MOVING

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCACTIVATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCCALCSIZE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCCREATE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCDESTROY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCHITTEST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCLBUTTONDBLCLK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCLBUTTONDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCLBUTTONUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCMBUTTONDBLCLK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCMBUTTONDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCMBUTTONUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCMOUSEMOVE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCPAINT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCRBUTTONDBLCLK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCRBUTTONDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NCRBUTTONUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NEXTDLGCTL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_NULL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PAINT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PAINTCLIPBOARD

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PAINTICON

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PALETTECHANGED

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PALETTEISCHANGING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PARENTNOTIFY

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PASTE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PENWINFIRST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PENWINLAST

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_POWER

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_POWERBROADCAST

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PRINT

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_PRINTCLIENT

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUERYDRAGICON

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUERYENDSESSION

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUERYNEWPALETTE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUERYOPEN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUEUESYNC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_QUIT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_RASDIALEVENT

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	ras.h
Unicode	No
Platform Notes	None


WM_RBUTTONDBLCLK

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_RBUTTONDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_RBUTTONUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_RENDERALLFORMATS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_RENDERFORMAT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETCURSOR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETFOCUS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETFONT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETHOTKEY

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETICON

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETREDRAW

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SETTEXT

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SHOWWINDOW

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SIZE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SIZECLIPBOARD

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SIZING

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SPOOLERSTATUS

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_STYLECHANGED

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_STYLECHANGING

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSCHAR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSCOLORCHANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSCOMMAND

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSDEADCHAR

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSKEYDOWN

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_SYSKEYUP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_TIMECHANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_TIMER

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_UNDO

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_USER

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_VKEYTOITEM

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_VSCROLL

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_VSCROLLCLIPBOARD

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_WINDOWPOSCHANGED

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_WINDOWPOSCHANGING

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WM_WININICHANGE

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WS_EX_CLIENTEDGE

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WS_EX_MDICHILD

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


WS_EX_WINDOWEDGE

Windows NT	No
Win95	Yes
Win32s	No
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


LVN_PEN

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File
Unicode
Platform Notes	None


CWPRETSTRUCT

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	winuser.h
Unicode
Platform Notes	None


DRIVER_INFO_3

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	winspool.h
Unicode
Platform Notes	None


PORT_INFO_2

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	winspool.h
Unicode
Platform Notes	None


PRINTER_INFO_3

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	winspool.h
Unicode
Platform Notes	None


PRINTER_INFO_5

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	winspool.h
Unicode
Platform Notes	None


QUERY_SERVICE_CONFIG

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	winsvc.h
Unicode
Platform Notes	None


SERVICE_ADDRESS

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	nspapi.h
Unicode
Platform Notes	None


SERVICE_ADDRESSES

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	nspapi.h
Unicode
Platform Notes	None


SERVICE_INFO

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	nspapi.h
Unicode
Platform Notes	None


SERVICE_STATUS

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	winsvc.h
Unicode
Platform Notes	None


SERVICE_TABLE_ENTRY

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	winsvc.h
Unicode
Platform Notes	None


SERVICE_TYPE_INFO_ABS

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	nspapi.h
Unicode
Platform Notes	None


SERVICE_TYPE_VALUE_ABS

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	nspapi.h
Unicode
Platform Notes	None


SET_PARTITION_INFORMATION

Windows NT	Yes
Win95	No
Win32s
Import Library
Header File	winioctl.h
Unicode
Platform Notes	None


TPMPARAMS

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File	winuser.h
Unicode
Platform Notes	None


ICDrawSuggestFormat

Windows NT
Win95	Yes
Win32s
Import Library
Header File
Unicode
Platform Notes	None


RegisterServiceProcess

Windows NT
Win95
Win32s
Import Library
Header File	winbase.h
Unicode
Platform Notes	None


ChangeClipboardChain

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ChangeDisplaySettings

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ChangeMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


ChangeServiceConfig

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


char_array_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


char_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


CharLower

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharLowerBuff

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharNext

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharPrev

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharToOem

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharToOemBuff

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharUpper

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CharUpperBuff

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CheckColorsInGamut

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


CheckDlgButton

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CheckMenuItem

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CheckMenuRadioItem

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CheckRadioButton

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ChildWindowFromPoint

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ChildWindowFromPointEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ChooseColor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.dll
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


ChooseFont

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.dll
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


ChoosePixelFormat

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


Chord

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ClearCommBreak

Windows NT	New
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ClearCommError

Windows NT	New
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ClearEventLog

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ClientToScreen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ClipCursor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CloseClipboard

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CloseDesktop

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CloseEnhMetaFile

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


CloseEventLog

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


CloseFigure

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CloseHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


CloseMetaFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


ClosePrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


CloseServiceHandle

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	No
Platform Notes	None


closesocket

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


CloseWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CloseWindowStation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CLSIDFromProgID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


CLSIDFromString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


CoBuildVersion

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoCreateGuid

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoCreateInstance

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoDisconnectObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoDosDateTimeToFileTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoFileTimeNow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoFileTimeToDosDateTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoFreeAllLibraries

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoFreeLibrary

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoFreeUnusedLibraries

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoGetClassObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoGetCurrentProcess

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoGetMalloc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoGetMarshalSizeMax

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoGetStandardMarshal

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoGetState

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoGetTreatAsClass

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoInitialize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoIsHandlerConnected

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoIsOle1Class

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoLoadLibrary

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoLockObjectExternal

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


ColorMatchToTarget

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


CoMarshalHresult

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoMarshalInterface

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CombineRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CombineTransform

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


CommandLineToArgvW

Windows NT	New
Win95	No
Win32s	New
Import Library	shell32.dll
Header File	shellapi.h
Unicode	No
Platform Notes	None


CommConfigDialog

Windows NT	New
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CommDlgExtendedError

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.dll
Header File	commdlg.h
Unicode	No
Platform Notes	None


CompareFileTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


CompareString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


ConfigurePort

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


connect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


ConnectNamedPipe

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ConnectToPrinterDlg

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


ContinueDebugEvent

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ControlService

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	No
Platform Notes	None


ConvertDefaultLocale

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


CopyAcceleratorTable

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CopyCursor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CopyEnhMetaFile

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


CopyFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CopyIcon

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CopyImage

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CopyLZFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.dll
Header File	lzexpand.h
Unicode	No
Platform Notes	None


CopyMemory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


CopyMetaFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CopyRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CopySid

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


CoRegisterClassObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoRegisterMessageFilter

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoReleaseMarshalData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoRevokeClassObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoTaskMemAlloc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoTaskMemFree

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoTaskMemRealloc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoTreatAsClass

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoUninitialize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoUnmarshalHresult

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CoUnmarshalInterface

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CountClipboardFormats

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateAcceleratorTable

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateAntiMoniker

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CreateBindCtx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CreateBitmap

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateBitmapIndirect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateBrushIndirect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateCaret

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateColorSpace

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


CreateCompatibleBitmap

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateCompatibleDC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateConsoleScreenBuffer

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


CreateCursor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateDataAdviseHolder

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CreateDataCache

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CreateDC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateDesktop

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateDialog

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateDialogIndirect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateDialogIndirectParam

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateDialogParam

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateDIBitmap

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateDIBPatternBrush

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateDIBPatternBrushPt

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


CreateDIBSection

Windows NT	New
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


CreateDirectory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateDirectoryEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateDiscardableBitmap

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateDispTypeInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


CreateEditableStream

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


CreateEllipticRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreateEllipticRgnIndirect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreateEnhMetaFile

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


CreateErrorInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


CreateEvent

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateFileMapping

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateFileMoniker

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


CreateFont

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateFontIndirect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateGenericComposite

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CreateHalftonePalette

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


CreateHatchBrush

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateIC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateIcon

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateIconFromResource

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateIconFromResourceEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateIconIndirect

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateILockBytesOnHGlobal

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


CreateIoCompletionPort

Windows NT	New
Win95	No
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateItemMoniker

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


CreateMailslot

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateMappedBitmap

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


CreateMDIWindow

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


CreateMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateMetaFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateMutex

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateNamedPipe

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateOleAdviseHolder

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


CreatePalette

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreatePatternBrush

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreatePen

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreatePenIndirect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreatePipe

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


CreatePointerMoniker

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


CreatePolygonRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreatePolyPolygonRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreatePopupMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


CreatePrivateObjectSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateProcess

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateProcessAsUser

Windows NT	Yes
Win95
Win32s
Import Library
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreatePropertySheetPage

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	prsht.h
Unicode	WinNT
Platform Notes	None


CreateRectRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreateRectRgnIndirect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreateRemoteThread

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateRoundRectRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


CreateScalableFontResource

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


CreateSemaphore

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


CreateService

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


CreateSolidBrush

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


CreateStatusWindow

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


CreateStdDispatch

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


CreateStreamOnHGlobal

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


CreateTapePartition

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateThread

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


CreateToolbarEx

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


CreateTypeLib

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


CreateUpDownControl

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


CreateWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


CreateWindowEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	hMenu limited to WORD on Win32s


CreateWindowStation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


data_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


data_into_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


data_size_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


DceErrorInqText

Windows NT	New
Win95
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcdce.h
Unicode	WinNT
Platform Notes	None


DdeAbandonTransaction

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeAccessData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeAddData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeClientTransaction

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeCmpStringHandles

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeConnect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeConnectList

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeCreateDataHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeCreateStringHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	WinNT
Platform Notes	None


DdeDisconnect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeDisconnectList

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeEnableCallback

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeFreeDataHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeFreeStringHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeGetData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeGetLastError

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeImpersonateClient

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeInitialize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	WinNT
Platform Notes	None


DdeKeepStringHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeNameService

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdePostAdvise

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeQueryConvInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeQueryNextServer

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeQueryString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	WinNT
Platform Notes	None


DdeReconnect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeSetQualityOfService

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	dde.h
Unicode	No
Platform Notes	None


DdeSetUserHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeUnaccessData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DdeUninitialize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	ddeml.h
Unicode	No
Platform Notes	None


DebugActiveProcess

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DebugBreak

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DefDlgProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DefDriverProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DeferWindowPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DefFrameProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DefHookProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


DefineDosDevice

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DefineHandleTable

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


DefMDIChildProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DefScreenSaverProc

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	scrnsave.dll
Header File	scrnsave.h
Unicode	No
Platform Notes	None


DefWindowProc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DeleteAce

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DeleteAtom

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DeleteColorSpace

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


DeleteCriticalSection

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DeleteDC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


DeleteEnhMetaFile

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


DeleteFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


DeleteForm

Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeleteMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DeleteMetaFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


DeleteMonitor

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeleteObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Suceeds the deletion if the object is currently selected into a DC and creates a Zombie object. Windows NT: Fails the call.


DeletePort

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeletePrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


DeletePrinterDriver

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeletePrintProcessor

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeletePrintProvidor

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DeleteService

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	No
Platform Notes	None


DeregisterEventSource

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DescribePixelFormat

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


DestroyAcceleratorTable

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DestroyCaret

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DestroyCursor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DestroyIcon

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DestroyMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DestroyPrivateObjectSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DestroyPropertySheetPage

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	prsht.h
Unicode	No
Platform Notes	None


DestroyWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DeviceCapabilitiesEx

Windows NT	New
Win95	Yes
Win32s	New
Import Library	gdi32.dll
Header File
Unicode	No
Platform Notes	None


DeviceIoControl

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DialogBox

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


DialogBoxIndirect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


DialogBoxIndirectParam

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DialogBoxParam

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DisableThreadLibraryCalls

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DisconnectNamedPipe

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DispatchMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DispGetIDsOfNames

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


DispGetParam

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


DispInvoke

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


DlgDirList

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DlgDirListComboBox

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DlgDirSelectComboBoxEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DlgDirSelectEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DllEntryPoint

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File
Unicode	No
Platform Notes	None


DllGetClassObject

Windows NT
Win95
Win32s
Import Library
Header File	objbase.h
Unicode
Platform Notes	None


DocumentProperties

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


DoDragDrop

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


DosDateTimeToFileTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DosDateTimeToVariantTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


double_array_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


double_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


DPtoLP

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


DragAcceptFiles

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.dll
Header File	shellapi.h
Unicode	No
Platform Notes	None


DragDetect

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DragFinish

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.dll
Header File	shellapi.h
Unicode	No
Platform Notes	None


DragObject

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DragQueryFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.dll
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


DragQueryPoint

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.dll
Header File	shellapi.h
Unicode	No
Platform Notes	None


DrawAnimatedRects

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawCaption

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawDibBegin

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibChangePalette

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibClose

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibDraw

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibEnd

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibGetBuffer

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibGetPalette

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibOpen

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibProfileDisplay

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibRealize

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibSetPalette

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibStart

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibStop

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawDibTime

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


DrawEdge

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawEscape

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


DrawFocusRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawFrameControl

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawIcon

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawIconEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawInsert

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


DrawMenuBar

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawState

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DrawStatusText

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	WinNT
Platform Notes	None


DrawText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


DrawTextEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


DriverCallback

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	digitalv.h
Unicode	No
Platform Notes	None


DrvGetModuleHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DrvSendMessage

Windows NT
Win95	Yes
Win32s
Import Library
Header File	mmsystem.h
Unicode	No
Platform Notes	None


DuplicateHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


DuplicateIcon

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	shell32.dll
Header File	shellapi.h
Unicode	No
Platform Notes	None


DuplicateToken

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


EditStreamClone

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


EditStreamCopy

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


EditStreamCut

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


EditStreamPaste

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	No
Platform Notes	None


EditStreamSetInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


EditStreamSetName

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


Ellipse

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


EmptyClipboard

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EnableMenuItem

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EnableScrollBar

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EnableWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EndDeferWindowPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EndDialog

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EndDoc

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


EndDocPrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


EndPage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


EndPagePrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


EndPaint

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EndPath

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


EndUpdateResource

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


EnterCriticalSection

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


enum_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


EnumCalendarInfo

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumChildWindows

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumClipboardFormats

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumDateFormats

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumDependentServices

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


EnumDesktops

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EnumDesktopWindows

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumDisplaySettings

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EnumEnhMetaFile

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


EnumFontFamilies

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


EnumFontFamiliesEx

Windows NT	No
Win95	Yes
Win32s
Import Library
Header File
Unicode
Platform Notes	None


EnumFonts

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


EnumForms

Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumICMProfiles

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


EnumJobs

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumMetaFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


EnumMonitors

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumObjects

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


EnumPorts

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumPrinterDrivers

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumPrinters

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumPrintProcessorDatatypes

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumPrintProcessors

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


EnumProps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EnumPropsEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EnumProtocols

Windows NT	Yes
Win95
Win32s	No
Import Library	wsock32.dll
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


EnumResourceLanguages

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	573
Platform Notes	,New,WinNT, Win95


EnumResourceNames

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	574
Platform Notes	,New,WinNT, Win95


EnumResourceTypes

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	575
Platform Notes	,New,WinNT, Win95


EnumServicesStatus

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


EnumSystemCodePages

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumSystemLocales

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumTaskWindows

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumThreadWindows

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumTimeFormats

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


EnumWindows

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EnumWindowStations

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


EqualPrefixSid

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


EqualRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


EqualRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


EqualSid

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


EraseTape

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


Escape

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


EscapeCommFunction

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ExcludeClipRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ExcludeUpdateRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ExitProcess

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ExitThread

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


ExitWindows

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


ExitWindowsEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


ExpandEnvironmentStrings

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ExtCreatePen

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	New
Platform Notes	Windows 95: Only supports solid colors (e.g.


ExtCreateRegion

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Fails if the transform involves a shearing or rotation; int == 16 bits


ExtEscape

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


ExtFloodFill

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ExtractAssociatedIcon

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	shell32.dll
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


ExtractIcon

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.dll
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


ExtractIconEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library
Header File	shellapi.h
Unicode
Platform Notes	None


ExtSelectClipRgn

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


ExtTextOut

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: 16-bit coordinates only


FatalAppExit

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FatalExit

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FileTimeToDosDateTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FileTimeToLocalFileTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	Win32s always uses LocalTime never UTC


FileTimeToSystemTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FillConsoleOutputAttribute

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


FillConsoleOutputCharacter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


FillMemory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


FillPath

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


FillRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


FillRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


FindAtom

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FindClose

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FindCloseChangeNotification

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FindClosePrinterChangeNotification

Windows NT	New
Win95	No
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


FindExecutable

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	shell32.dll
Header File	shellapi.h
Unicode	WinNT
Platform Notes	None


FindFirstChangeNotification

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FindFirstFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	Win32s returns times in LocalTime


FindFirstFreeAce

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FindFirstPrinterChangeNotification

Windows NT	New
Win95	No
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


FindNextChangeNotification

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FindNextFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	Win32s returns times in LocalTime


FindNextPrinterChangeNotification

Windows NT	New
Win95	No
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	No
Platform Notes	None


FindResource

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	631
Platform Notes	,Widened,WinNT, Win95


FindResourceEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	632
Platform Notes	,New,WinNT, Win95


FindText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.dll
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


FindWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


FindWindowEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


FixBrushOrgEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


FlashWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


FlattenPath

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


float_array_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


float_from_ndr

Windows NT	Yes
Win95	No
Win32s	No
Import Library	rpcrt4.dll
Header File	rpcndr.h
Unicode
Platform Notes	None


FloodFill

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


FlushConsoleInputBuffer

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


FlushFileBuffers

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FlushInstructionCache

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	This is valid on SMP platforms only; Windows 95 returns a constant


FlushViewOfFile

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FoldString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


FormatMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FrameRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


FrameRgn

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


FreeConsole

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


FreeDDElParam

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	dde.h
Unicode	No
Platform Notes	None


FreeEnvironmentStrings

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


FreeImageColorMatcher

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


FreeLibrary

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FreeLibraryAndExitThread

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FreeModule

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


FreeProcInstance

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


FreeResource

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


FreeSid

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GdiComment

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GdiFlush

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GdiGetBatchLimit

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GdiSetBatchLimit

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GenerateConsoleCtrlEvent

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


GetAce

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetAclInformation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetACP

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


GetActiveObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


GetActiveWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetAddressByName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	wsock32.dll
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


GetArcDirection

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetAspectRatioFilterEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetAsyncKeyState

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetAtomName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetBinaryType

Windows NT	New
Win95	No
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetBitmapBits

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetBitmapDimensionEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetBkColor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetBkMode

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetBoundsRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetBrushOrgEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetCapture

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetCaretBlinkTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetCaretPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetCharABCWidths

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetCharABCWidthsFloat

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetCharacterPlacement

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetCharWidth

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT; Win95
Platform Notes	Windows 95: int == 16 bits


GetCharWidth32

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetCharWidthFloat

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetClassFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	WinNT; Win95; Win32s
Platform Notes	All 32-bit OLE Apis are UNICODE only


GetClassInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetClassInfoEx

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetClassLong

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetClassName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetClassWord

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClientRect

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClipboardData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClipboardFormatName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetClipboardOwner

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClipboardViewer

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClipBox

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetClipCursor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetClipRgn

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetColorAdjustment

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetColorSpace

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetCommandLine

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	717
Platform Notes	,New,WinNT, Win95


GetCommConfig

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCommMask

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCommModemStatus

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCommProperties

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCommState

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCommTimeouts

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCompressedFileSize

Windows NT	New
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetComputerName

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetConsoleCP

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	Windows 95 limitations


GetConsoleCursorInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


GetConsoleMode

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


GetConsoleOutputCP

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	Windows 95 limitations


GetConsoleScreenBufferInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


GetConsoleTitle

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	WinNT
Platform Notes	None


GetConvertStg

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


GetCPInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


GetCurrencyFormat

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetCurrentDirectory

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetCurrentObject

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetCurrentPositionEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetCurrentProcess

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCurrentProcessId

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCurrentThread

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCurrentThreadId

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCurrentTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


GetCursor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetCursorPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDateFormat

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetDC

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDCEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDCOrgEx

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetDefaultCommConfig

Windows NT	No
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetDesktopWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDeviceCaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetDeviceGammaRamp

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetDialogBaseUnits

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDIBColorTable

Windows NT	New
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetDIBits

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetDiskFreeSpace

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetDlgCtrlID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDlgItem

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDlgItemInt

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDlgItemText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetDoubleClickTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetDriverModuleHandle

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winmm.dll
Header File	mmsystem.h
Unicode	No
Platform Notes	None


GetDriveType

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetEffectiveClientRect

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	commctrl.h
Unicode	No
Platform Notes	None


GetEnhMetaFile

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetEnhMetaFileBits

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetEnhMetaFileDescription

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetEnhMetaFileHeader

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetEnhMetaFilePaletteEntries

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetEnvironmentStrings

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetEnvironmentVariable

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetErrorInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	oleaut32.dll
Header File	oleauto.h
Unicode	No
Platform Notes	None


GetExitCodeProcess

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetExitCodeThread

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetExpandedName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	lz32.dll
Header File	lzexpand.h
Unicode	WinNT
Platform Notes	None


GetFileAttributes

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetFileInformationByHandle

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetFileSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetFileSize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetFileTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetFileTitle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.dll
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


GetFileType

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetFileVersionInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	version.dll
Header File	winver.h
Unicode	WinNT
Platform Notes	None


GetFileVersionInfoSize

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	version.dll
Header File	winver.h
Unicode	WinNT
Platform Notes	None


GetFocus

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetFontData

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetFontLanguageInfo

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetForegroundWindow

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetForm

Windows NT	Yes
Win95	No
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetFreeSpace

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


GetFullPathName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetGlyphOutline

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetGraphicsMode

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: Only GM_COMPATIBLE is supported


GetHandleInformation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetHGlobalFromILockBytes

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


GetHGlobalFromStream

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	ole2.h
Unicode	No
Platform Notes	None


gethostbyaddr

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


gethostbyname

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


gethostname

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


GetICMProfile

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetIconInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetInputState

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetJob

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetKBCodePage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetKernelObjectSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetKerningPairs

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetKeyboardLayout

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetKeyboardLayoutList

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetKeyboardLayoutName

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	Windows 95: Only 1 keybrd loaded at once


GetKeyboardState

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetKeyboardType

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetKeyNameText

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetKeyState

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetLargestConsoleWindowSize

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


GetLastActivePopup

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetLastError

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetLengthSid

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetLocaleInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetLocalTime

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetLogColorSpace

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	None


GetLogicalDrives

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetLogicalDriveStrings

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetMailslotInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetMapMode

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetMenu

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuCheckMarkDimensions

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuContextHelpId

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuDefaultItem

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuItemCount

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuItemID

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuItemInfo

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetMenuItemRect

Windows NT	Stub
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuState

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMenuString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetMessage

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


GetMessageExtraInfo

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMessagePos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMessageTime

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetMetaFile

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetMetaFileBitsEx

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetMetaRgn

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetMiterLimit

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetModuleFileName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetModuleHandle

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetNameByType

Windows NT	Yes
Win95
Win32s	No
Import Library	wsock32.dll
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


GetNamedPipeHandleState

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetNamedPipeInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetNearestColor

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetNearestPaletteIndex

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetNextDlgGroupItem

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetNextDlgTabItem

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetNextWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library
Header File	winuser.h
Unicode	No
Platform Notes	None


GetNumberFormat

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winnls.h
Unicode	WinNT
Platform Notes	None


GetNumberOfConsoleInputEvents

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


GetNumberOfConsoleMouseButtons

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	wincon.h
Unicode	No
Platform Notes	None


GetNumberOfEventLogRecords

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetObject

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetObjectType

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetOEMCP

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winnls.h
Unicode	No
Platform Notes	None


GetOldestEventLogRecord

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetOpenClipboardWindow

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetOpenFileName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.dll
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


GetOpenFileNamePreview

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


GetOutlineTextMetrics

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	WinNT
Platform Notes	Windows 95: int == 16 bits


GetOverlappedResult

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	Windows 95: Only on serial and IOCTL devices


GetPaletteEntries

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetParent

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetPath

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


getpeername

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


GetPixel

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: 16-bit coordinates only


GetPixelFormat

Windows NT	Yes
Win95	No
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	None


GetPolyFillMode

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetPrinter

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetPrinterData

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetPrinterDriver

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetPrinterDriverDirectory

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetPrintProcessorDirectory

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	winspool.dll
Header File	winspool.h
Unicode	WinNT
Platform Notes	None


GetPriorityClass

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetPriorityClipboardFormat

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetPrivateObjectSecurity

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetPrivateProfileInt

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetPrivateProfileSection

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetPrivateProfileSectionNames

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetPrivateProfileString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetPrivateProfileStruct

Windows NT	Yes
Win95	Yes
Win32s
Import Library
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetProcAddress

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessAffinityMask

Windows NT	New
Win95	New
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	This is valid on SMP platforms only; Windows 95 returns a constant


GetProcessHeap

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessHeaps

Windows NT	New
Win95	Yes
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessShutdownParameters

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessTimes

Windows NT	Yes
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessVersion

Windows NT	New
Win95	New
Win32s
Import Library
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProcessWindowStation

Windows NT	Yes
Win95	No
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetProcessWorkingSetSize

Windows NT	New
Win95	No
Win32s	No
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetProfileInt

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetProfileSection

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetProfileSectionNames

Windows NT	Yes
Win95
Win32s
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetProfileString

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


GetProp

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	WinNT
Platform Notes	None


getprotobyname

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


getprotobynumber

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


GetQueuedCompletionStatus

Windows NT	New
Win95	No
Win32s	New
Import Library	kernel32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetQueueStatus

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetRasterizerCaps

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetRegionData

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetResourceID

Windows NT
Win95
Win32s
Import Library
Header File
Unicode
Platform Notes	None


GetRgnBox

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetROP2

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	gdi32.dll
Header File	wingdi.h
Unicode	No
Platform Notes	Windows 95: int == 16 bits


GetRunningObjectTable

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	ole32.dll
Header File	objbase.h
Unicode	No
Platform Notes	None


GetSaveFileName

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	comdlg32.dll
Header File	commdlg.h
Unicode	WinNT
Platform Notes	None


GetSaveFileNamePreview

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	vfw32.dll
Header File	vfw.h
Unicode	WinNT
Platform Notes	None


GetScrollInfo

Windows NT	Yes
Win95	Yes
Win32s	No
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetScrollPos

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetScrollRange

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	user32.dll
Header File	winuser.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorControl

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorDacl

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorGroup

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorLength

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorOwner

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


GetSecurityDescriptorSacl

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winbase.h
Unicode	No
Platform Notes	None


getservbyname

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


getservbyport

Windows NT	Yes
Win95	Yes
Win32s	Yes
Import Library	wsock32.dll
Header File	winsock.h
Unicode	No
Platform Notes	None


GetService

Windows NT	Yes
Win95
Win32s	No
Import Library	wsock32.dll
Header File	nspapi.h
Unicode	WinNT
Platform Notes	None


GetServiceDisplayName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


GetServiceKeyName

Windows NT	Yes
Win95	No
Win32s	No
Import Library	advapi32.dll
Header File	winsvc.h
Unicode	WinNT
Platform Notes	None


GetShortPathName

Windows NT	New
Win95	Yes
Win32s	Yes
Import Library	kernel32.dll
Header File	winbase.h
Unicode	WinNT
Platform Notes	None


ABC

typedef struct _ABC { // abc

    int     abcA;

    UINT    abcB;

    int     abcC;

} ABC;

The ABC structure contains the width of a character in a TrueType font.

Members

abcA

Specifies the "A" spacing of the character. The "A" spacing is the distance to add to the current position before drawing the character glyph.

abcB

Specifies the "B" spacing of the character. The "B" spacing is the width of the drawn portion of the character glyph.

abcC

Specifies the "C" spacing of the character. The "C" spacing is the distance to add to the current position to provide white space to the right of the character glyph.

Remarks

The total width of a character is the summation of the "A," "B," and "C" spaces. Either the "A" or the "C" space can be negative to indicate underhangs or overhangs.

See Also

GetCharABCWidths


ABCFLOAT

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.

Members

abcfA

Specifies the "A" spacing of the character. The "A" spacing is the distance to add to the current position before drawing the character glyph.

abcfB

Specifies the "B" spacing of the character. The "B" spacing is the width of the drawn portion of the character glyph.

abcfC

Specifies the "C" spacing of the character. The "C" spacing is the distance to add to the current position to provide white space to the right of the character glyph.

Remarks

The A, B, and C widths are measured along the base line of the font.

The character increment (total width) of a character is the sum of the "A," "B," and "C" spaces. Either the "A" or the "C" space can be negative to indicate underhangs or overhangs.

See Also

GetCharABCWidthsFloat


ACCEL

typedef struct tagACCEL { // accl

    BYTE   fVirt;

    WORD   key;

    WORD   cmd;

} ACCEL;

The ACCEL structure defines an accelerator key used in an accelerator table.

Members

fVirt

Specifies the accelerator flags. This member can be a combination of the following values:

Value	Meaning
FALT	The ALT key must be held down when the accelerator key is pressed.
FCONTROL	The CTRL key must be held down when the accelerator key is pressed.
FNOINVERT	Specifies that no top-level menu item is highlighted when the accelerator is used. If this flag is not specified, a top-level menu item will be highlighted, if possible, when the accelerator is used.
FSHIFT	The SHIFT key must be held down when the accelerator key is pressed.
FVIRTKEY	The key member specifies a virtual-key code. If this flag is not specified, key is assumed to specify an ASCII character code.
key

Specifies the accelerator key. This member can be either a virtual-key code or an ASCII character code.

cmd

Specifies the accelerator identifier. This value is placed in the low-order word of the wParam parameter of the WM_COMMAND or WM_SYSCOMMAND message when the accelerator is pressed.

See Also

WM_COMMAND, WM_SYSCOMMAND


ACCESS_ALLOWED_ACE

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).

Members

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.

Remarks

ACE structures must be aligned on doubleword boundaries. All Windows memory-management functions return doubleword-aligned handles to memory.

See Also

AddAccessAllowedAce, AddAce, GetAce, ACCESS_DENIED_ACE, ACCESS_MASK, ACE_HEADER, ACL, SID, SYSTEM_ALARM_ACE, SYSTEM_AUDIT_ACE


ACCESS_DENIED_ACE

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).

Members

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.

Remarks

ACE structures must be aligned on doubleword boundaries. All Windows memory-management functions return doubleword-aligned handles to memory.

See Also

AddAccessDeniedAce, ACCESS_ALLOWED_ACE, ACCESS_MASK, ACE_HEADER, ACL, SID, SYSTEM_ALARM_ACE, SYSTEM_AUDIT_ACE


ACCESS_MASK

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. Contains the access mask specific to the object type associated with the mask.
16 through 23	Standard rights. Contains the object's standard access rights and can be a combination of the following predefined flags:
	Bit	Flag	Meaning
	16	DELETE	Delete access
	17	READ_CONTROL	Read access to the owner, group, and discretionary access-control list (ACL) of the security descriptor
	18	WRITE_DAC	Write access to the discretionary access-control list (ACL)
	19	WRITE_OWNER	Write access to owner
	20	SYNCHRONIZE	Windows NT: Synchronize access
Bits	Meaning
24	Access system security (ACCESS_SYSTEM_SECURITY). This flag is not a typical access type. It is used to indicate access to a system ACL. This type of access requires the calling process to have a specific privilege.
25	Maximum allowed (MAXIMUM_ALLOWED)
26 through 27	Reserved
28	Generic all (GENERIC_ALL)
29	Generic execute (GENERIC_EXECUTE)
30	Generic write (GENERIC_WRITE)
31	Generic read (GENERIC_READ)
The following constants represent the specific and standard access rights:

#define SPECIFIC_RIGHTS_ALL           0x0000FFFF

#define STANDARD_RIGHTS_REQUIRED      0x000F0000

#define STANDARD_RIGHTS_ALL           0x001F0000

See Also

GENERIC_MAPPING


ACCESSTIMEOUT

typedef struct tagACCESSTIMEOUT {     // ato

    UINT  cbSize;

    DWORD dwFlags;

    DWORD iTimeOutMSec;

} ACCESSTIMEOUT;

The ACCESSTIMEOUT structure contains information about the time-out period associated with the Win32 accessibility features. The accessibility time-out period is the length of time that must pass without keyboard and mouse input before the operating system automatically turns off accessibility features. The accessibility features affected by the time-out are the FilterKeys features (SlowKeys, BounceKeys, and RepeatKeys), MouseKeys, ToggleKeys, and StickyKeys. The accessibility time-out is designed for computers that are shared by several users so that options selected by one user do not inconvenience a subsequent user.

Windows 95 only: The accessibility time-out affects the High Contrast Mode setting.

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

A set of bit flags that specify properties of the time-out behavior for accessibility features. The following values are defined:

Value	Meaning
ATF_ONOFFFEEDBACK	If this flag is set, the operating system plays a descending siren sound when the time-out period elapses and the accessibility features are turned off.
ATF_AVAILABLE	If this flag is set, you can set a time-out period for accessibility features. An application can retrieve this value, but cannot set it.
ATF_TIMEOUTON	If this flag is set, a time-out period has been set for accessibility features. If this flag is not set, the features will not time out even though a time-out period is specified.
iTimeOutMSec

Specifies the time-out period, in milliseconds.

Remarks

Use an ACCESSTIMEOUT structure when calling the SystemParametersInfo function with the uiAction parameter set to the SPI_GETACCESSTIMEOUT or SPI_SETACCESSTIMEOUT value. When using SPI_GETACCESSTIMEOUT, you must specify the cbSize member of the ACCESSTIMEOUT structure; the SystemParametersInfo function fills in the remaining members. Specify all structure members when using the SPI_SETACCESSTIMEOUT value.

See Also

SystemParametersInfo


ACE

An ACE is an access-control entry (ACE) in an access-control list (ACL).

Following are the currently defined ACE types:

ACE type	Structure	ACL Type
Access allowed	ACCESS_ALLOWED_ACE	Discretionary
Access denied	ACCESS_DENIED_ACE	Discretionary
System alarm	SYSTEM_ALARM_ACE	System
System audit	SYSTEM_AUDIT_ACE	System
System-alarm ACEs are not supported in the current version of Windows NT.

Remarks

An ACL contains a list of ACEs. An ACE defines access to an object for a specific user or group or defines the types of access that generate system-administration messages or alarms for a specific user or group. The user or group is identified by a security identifier (SID).

Each ACE starts with an ACE_HEADER structure. The format of the data following the header varies according to the ACE type specified in the header.

See Also

AddAce, ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACL, SYSTEM_ALARM_ACE, SYSTEM_AUDIT_ACE


ACE_HEADER

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).

Members

AceType

Specifies the ACE type. This member can be one of the following values:

Value	ACE type
ACCESS_ALLOWED_ACE_TYPE	Access-allowed (defined by the ACCESS_ALLOWED_ACE structure)
ACCESS_DENIED_ACE_TYPE	Access-denied (defined by the ACCESS_DENIED_ACE structure)
SYSTEM_AUDIT_ACE_TYPE	System-audit (defined by the SYSTEM_AUDIT_ACE structure)
System-alarm ACEs are not supported in the current version of Windows NT. Applications cannot use the SYSTEM_ALARM_ACE_TYPE value or SYSTEM_ALARM_ACE structure.

AceFlags

Specifies a set of ACE type-specific control flags. This member can be a combination of the following values:

Value	Meaning
CONTAINER_INHERIT_ACE
	The ACE is inherited by container objects, such as directories.
INHERIT_ONLY_ACE
	The ACE does not apply to the container object, but to objects contained by it.
NO_PROPAGATE_INHERIT_ACE
	The OBJECT_INHERIT_ACE and CONTAINER_INHERIT_ACE bits are not propagated to an inherited ACE.
OBJECT_INHERIT_ACE
	The ACE is inherited by noncontainer objects, such as files created within the container object to which the ACE is assigned.
FAILED_ACCESS_ACE_FLAG
	Used with system-audit and system-alarm ACEs to indicate a message is generated for failed access attempts.
SUCCESSFUL_ACCESS_ACE_FLAG
	Used with system-audit and system-alarm ACEs to indicate a message is generated for successful access attempts.
AceSize

Specifies the size, in bytes, of the ACE.

Remarks

An ACE defines access to an object for a specific user or group or defines the types of access that generate system-administration messages or alarms for a specific user or group. The user or group is identified by a security identifier (SID).

See Also

ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACL, SYSTEM_ALARM_ACE, SYSTEM_AUDIT_ACE


ACL

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).

Members

AclRevision

Specifies the ACL's revision level. This value should be ACL_REVISION. All ACEs in an ACL must be at the same revision level.

Sbz1

Specifies a zero byte of padding that aligns the AclRevision member on a 16-bit boundary.

AclSize

Specifies the size, in bytes, of the ACL. This value includes both the ACL structure and all the ACEs.

AceCount

Specifies the number of ACEs stored in the ACL.

Sbz2

Specifies two zero bytes of padding that align the ACL structure on a 32-bit boundary.

Remarks

An ACL includes a sequential list of zero or more ACEs. The individual ACEs in an ACL are numbered from 0 to n, where n+1 is the number of ACEs in the ACL. When editing an ACL, an application refers to an ACE within the ACL by its index.

There are two types of ACL: discretionary and system.

A discretionary ACL is controlled by the owner of an object or anyone granted WRITE_DAC access to the object. It specifies the access particular users and groups can have to an object. For example, the owner of a file can use a discretionary ACL to control which users and groups can and cannot have access to the file.

An object may also have system-level security information associated with it, in the form of a system ACL controlled by a system administrator. A system ACL can allow the system administrator to audit any attempts to gain access to an object.

Three ACE structures are currently defined:

ACE structure	Description
ACCESS_ALLOWED_ACE	Grants specified rights to a user or group. This ACE is stored in a discretionary ACL.
ACCESS_DENIED_ACE	Denies specified rights to a user or group. This ACE is stored in a discretionary ACL.
SYSTEM_AUDIT_ACE	Specifies what types of access will cause system-level audits. This ACE is stored in a system ACL.
A fourth ACE structure, SYSTEM_ALARM_ACE, is not currently supported by Windows NT.

The ACL structure is to be treated as though it were opaque and applications are not to attempt to work with its members directly. To ensure that ACLs are semantically correct, applications can use the functions listed in the SeeAlso section to create and manipulate ACLs.

Each ACL and ACE structure begins on a doubleword boundary.

See Also

AddAce, DeleteAce, GetAclInformation, GetSecurityDescriptorDacl, GetSecurityDescriptorSacl, InitializeAcl, IsValidAcl, SetAclInformation, SetSecurityDescriptorDacl, SetSecurityDescriptorSacl


ACL_REVISION_INFORMATION

typedef struct _ACL_REVISION_INFORMATION {

    DWORD   AclRevision;

} ACL_REVISION_INFORMATION;

The ACL_REVISION_INFORMATION structure contains revision information about an ACL structure.

Members

AclRevision

Specifies a revision number. The current revision number is ACL_REVISION.

See Also

GetAclInformation, SetAclInformation, ACL, ACL_INFORMATION_CLASS, ACL_SIZE_INFORMATION


ACL_SIZE_INFORMATION

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.

Members

AceCount

Specifies the number of access-control entries (ACEs) in the access-control list (ACL).

AclBytesInUse

Specifies the number of bytes in the ACL actually used to store the ACEs and ACL structure. This may be less than the total number of bytes allocated to the ACL.

AclBytesFree

Specifies the number of unused bytes in the ACL.

See Also

GetAclInformation, SetAclInformation, ACL, ACL_INFORMATION_CLASS, ACL_REVISION_INFORMATION


ACTION_HEADER

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.

Members

transport_id

Specifies the transport provider. This member can be used to check the validity of the request by the transport.

This member is always a four-character string. All strings starting with the letter M are reserved, as shown in the following example:

String	Meaning
M000	All transports
MNBF	NBF
MABF	AsyBEUI
MXNS	XNS
action_code

Specifies the action.

reserved

Reserved.

Remarks

The scope of the action is determined by the ncb_lsn and ncb_num members of the NCB structure, as follows:

	ncb_lsn = 0	ncb_lsn != 0
ncb_num = 0	Action applies to control channel associated with the valid LAN adapter.	Action applies to connection identifier associated with the valid local session number.
ncb_num != 0	Action applies to address associated with the valid LAN adapter.	Illegal combination.
See Also

NCB


ADAPTER_STATUS

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 required to describe the network adapters on the system.

Members

adapter_address

Specifies encoded address of the adapter.

rev_major

Specifies the major software-release level. This value is 3 for IBM NetBIOS 3. x.

reserved0

Reserved. This value is always zero.

adapter_type

Specifies the adapter type. This value is 0xFF for a Token Ring adapter or 0xFE for an Ethernet adapter.

rev_minor

Specifies the minor software-release level. This value is zero for IBM NetBIOS x.0.

duration

Specifies the duration of the reporting period, in minutes.

frmr_recv

Specifies the number of FRMR frames received.

frmr_xmit

Specifies the number of FRMR frames transmitted.

iframe_recv_err

Specifies the number of I frames received in error.

xmit_aborts

Specifies the number of aborted transmissions.

xmit_success

Specifies the number of successfully transmitted packets.

recv_success

Specifies the number of successfully received packets.

iframe_xmit_err

Specifies the number of I frames transmitted in error.

recv_buff_unavail

Specifies the number of times a buffer was not available to service a request from a remote computer.

t1_timeouts

Specifies the number of times that the DLC T1 timer timed out.

ti_timeouts

Specifies the number of times that the ti inactivity timer timed out.The ti timer is used to detect links that have been broken.

reserved1

Reserved. This value is always zero.

free_ncbs

Specifies the current number of free network control blocks.

max_cfg_ncbs

Undefined for IBM NetBIOS 3.0.

max_ncbs

Undefined for IBM NetBIOS 3.0.

xmit_buf_unavail

Undefined for IBM NetBIOS 3.0.

max_dgram_size

Specifies the maximum size of a datagram packet. This value is always at least 512 bytes.

pending_sess

Specifies the number of pending sessions.

max_cfg_sess

Specifies the configured maximum pending sessions.

max_sess

Undefined for IBM NetBIOS 3.0.

max_sess_pkt_size

Specifies the maximum size of a session data packet.

name_count

Specifies the number of names in the local names table.

See Also

NAME_BUFFER, NCB


ADDJOB_INFO_1

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.

Members

Path

Points to a null-terminated string that contains the path and filename that the application can use to store the print job.

JobId

Identifies the print job.

See Also

AddJob


ANIMATIONINFO

typedef struct tagANIMATIONINFO {

    UINT cbSize;

    int  iMinAnimate;

} ANIMATIONINFO, FAR *LPANIMATIONINFO;

The ANIMATIONINFO structure specifies the animation effects associated with user actions. This structure is used with the SystemParametersInfo function when the SPI_GETANIMATION or SPI_SETANIMATION action value is specified.

Members

cbSize

Specifies the size of the structure, in bytes.

iMinAnimate

Indicates that minimize and restore animation is enabled (if the member is a nonzero value) or not enabled (if zero).

See Also

SystemParametersInfo


APPBARDATA

typedef struct _AppBarData { // abd

    DWORD  cbSize;           // sizeof(APPBARDATA)

    HWND   hWnd;             // handle of appbar

    UINT   uCallbackMessage; // see below

    UINT   uEdge;            // see below

    RECT   rc;               // see below

    LPARAM lParam;           // see below

} APPBARDATA, *PAPPBARDATA;

Contains information that the system uses to process appbar messages.

Members

uCallbackMessage

Application-defined message identifier. The application uses the specified identifier for notification messages that it sends to the the appbar identified by the hWnd member. This member is used when sending the ABM_NEW message.

uEdge

Flag that specifies an edge of the screen. This member can be one of the following values:

ABE_BOTTOM	Bottom edge
ABE_LEFT	Left edge
ABE_RIGHT	Right edge
ABE_TOP	Top edge
This member is used when sending the ABM_GETAUTOHIDEBAR, ABM_QUERYPOS, ABM_SETAUTOHIDEBAR, and ABM_SETPOS messages.

rc

RECT structure that contains the bounding rectangle, in screen coordinates, of an appbar or the Windows taskbar. This member is used when sending the ABM_GETTASKBARPOS, ABM_QUERYPOS, and ABM_SETPOS messages.

lParam

Message-dependent value. This member is used with the ABM_SETAUTOHIDEBAR message.

Remarks

This structure is used with the SHAppBarMessage function.

See Also

SHAppBarMessage


BITMAP

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.

Members

bmType

Specifies the bitmap type. This member must be zero.

bmWidth

Specifies the width, in pixels, of the bitmap. The width must be greater than zero.

bmHeight

Specifies the height, in pixels, of the bitmap. The height must be greater than zero.

bmWidthBytes

Specifies the number of bytes in each scan line. This value must be divisible by 2, because Windows assumes that the bit values of a bitmap form an array that is word aligned.

bmPlanes

Specifies the count of color planes.

bmBitsPixel

Specifies the number of bits required to indicate the color of a pixel.

bmBits

Points to the location of the bit values for the bitmap. The bmBits member must be a long pointer to an array of character (1-byte) values.

Remarks

The bitmap formats currently used are monochrome and color. The monochrome bitmap uses a one-bit, one-plane format. Each scan is a multiple of 32 bits.

Scans are organized as follows for a monochrome bitmap of height n:

    Scan 0

    Scan 1

    .

    .

    .

    Scan n-2

    Scan n-1

The pixels on a monochrome device are either black or white. If the corresponding bit in the bitmap is 1, the pixel is set to the foreground color; if the corresponding bit in the bitmap is zero, the pixel is set to the background color.

All devices that have the RC_BITBLT device capability support bitmaps. For more information, see GetDeviceCaps.

Each device has a unique color format. To transfer a bitmap from one device to another, use the GetDIBits and SetDIBits functions.

See Also

CreateBitmapIndirect, GetObject


BITMAPCOREHEADER

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).

Members

bcSize

Specifies the number of bytes required by the structure.

bcWidth

Specifies the width of the bitmap, in pixels.

bcHeight

Specifies the height of the bitmap, in pixels.

bcPlanes

Specifies the number of planes for the target device. This value must be 1.

bcBitCount

Specifies the number of bits per pixel. This value must be 1, 4, 8, or 24.

Remarks

The BITMAPCOREINFO structure combines the BITMAPCOREHEADER structure and a color table to provide a complete definition of the dimensions and colors of a DIB. For more information about specifying a device-independent bitmap, see BITMAPCOREINFO structure.

An application should use the information stored in the bcSize member to locate the color table in a BITMAPCOREINFO structure, using a method such as the following:

pColor = ((LPBYTE) pBitmapCoreInfo +

        (WORD) (pBitmapCoreInfo -> bcSize))


BITMAPCOREINFO

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).

Members

bmciHeader

Specifies a BITMAPCOREHEADER structure that contains information about the dimensions and color format of a DIB.

bmciColors

Specifies an array of RGBTRIPLE structures that define the colors in the bitmap.

Remarks

A DIB consists of two parts: a BITMAPCOREINFO structure describing the dimensions and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits in the array are packed together, but each scan line must be padded with zeroes to end on a LONG boundary. The origin of the bitmap is the lower left corner.

The bcBitCount member of the BITMAPCOREHEADER structure determines the number of bits that define each pixel and the maximum number of colors in the bitmap. This member can be one of the following values:

Value	Meaning
1	The bitmap is monochrome, and the bmciColors member contains two entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first entry in the bmciColors table; if the bit is set, the pixel has the color of the second entry in the table.
4	The bitmap has a maximum of 16 colors, and the bmciColors member contains up to 16 entries. Each pixel in the bitmap is represented by a 4-bit index into the color table. For example, if the first byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel contains the color in the second table entry, and the second pixel contains the color in the sixteenth table entry.
8	The bitmap has a maximum of 256 colors, and the bmciColors member contains up to 256 entries. In this case, each byte in the array represents a single pixel.
24	The bitmap has a maximum of 2 (24)  colors, and the bmciColors member is NULL. Each three-byte triplet in the bitmap array represents the relative intensities of red, green, and blue, respectively, for a pixel.
The colors in the bmciColors table should appear in order of importance.

Alternatively, for functions that use DIBs, the bmciColors member can be an array of 16-bit unsigned integers that specify indices into the currently realized logical palette, instead of explicit RGB values. In this case, an application using the bitmap must call the DIB functions (CreateDIBitmap, CreateDIBPatternBrush, and CreateDIBSection) with the iUsage parameter set to DIB_PAL_COLORS.

Note  The bmciColors member should not contain palette indices if the bitmap is to be stored in a file or transferred to another application. Unless the application has exclusive use and control of the bitmap, the bitmap color table should contain explicit RGB values.

See Also

BITMAPCOREHEADER, CreateDIBitmap, CreateDIBPatternBrush, CreateDIBSection RGBTRIPLE


BITMAPFILEHEADER

typedef struct tagBITMAPFILEHEADER { // bmfh

        WORD    bfType;

        DWORD   bfSize;

        WORD    bfReserved1;

        WORD    bfReserved2;

        DWORD   bfOffBits;

} BITMAPFILEHEADER;

The BITMAPFILEHEADER structure contains information about the type, size, and layout of a file that contains a device-independent bitmap (DIB).

Members

bfType

Specifies the file type. It must be BM.

bfSize

Specifies the size, in bytes, of the bitmap file.

bfReserved1

Reserved; must be zero.

bfReserved2

Reserved; must be zero.

bfOffBits

Specifies the offset, in bytes, from the BITMAPFILEHEADER structure to the bitmap bits.

Remarks

A BITMAPINFO or BITMAPCOREINFO structure immediately follows the BITMAPFILEHEADER structure in the DIB file.

See Also

BITMAPCOREINFO, BITMAPINFO


BITMAPINFO

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).

Members

bmiHeader

Specifies a BITMAPINFOHEADER structure that contains information about the dimensions and color format of a DIB.

bmiColors

Specifies an array of RGBQUAD or doubleword data types that define the colors in the bitmap.

Remarks

A device-independent bitmap consists of two distinct parts: a BITMAPINFO structure describing the dimensions and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits in the array are packed together, but each scan line must be padded with zeroes to end on a LONG data-type boundary. If the height is positive, the bitmap is a bottom-up DIB and its origin is the lower left corner. If the height is negative, the bitmap is a top-down DIB and its origin is the upper left corner.

The biBitCount member of the BITMAPINFOHEADER structure determines the number of bits that define each pixel and the maximum number of colors in the bitmap. This member can be one of the following values:

Value	Meaning
1	The bitmap is monochrome, and the bmiColors member contains two entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first entry in the bmiColors table; if the bit is set, the pixel has the color of the second entry in the table.
4	The bitmap has a maximum of 16 colors, and the bmiColors member contains up to 16 entries. Each pixel in the bitmap is represented by a 4-bit index into the color table. For example, if the first byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel contains the color in the second table entry, and the second pixel contains the color in the sixteenth table entry.
8	The bitmap has a maximum of 256 colors, and the bmiColors member contains up to 256 entries. In this case, each byte in the array represents a single pixel.
16	The bitmap has a maximum of 2 (16)  colors. If the biCompression member of the BITMAPINFOHEADER is BI_RGB, the bmiColors member is NULL. Each WORD in the bitmap array represents a single pixel. The relative intensities of red, green, and blue are represented with 5 bits for each color component. The value for blue is in the least significant 5 bits, followed by 5 bits each for green and red, respectively. The most significant bit is not used. If the biCompression member of the BITMAPINFOHEADER is BI_BITFIELDS, the bmiColors member contains three DWORD color masks that specify the red, green, and blue components, respectively, of each pixel. 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 bitmap 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, for a pixel.
32	The bitmap has a maximum of 2 (32)  colors. If the biCompression member of the BITMAPINFOHEADER is BI_RGB, the bmiColors member is NULL. Each DWORD in the bitmap array represents the relative intensities of blue, green, and red, respectively, for a pixel. The high byte in each DWORD is not used. If the biCompression member of the BITMAPINFOHEADER is BI_BITFIELDS, the bmiColors member contains three DWORD color masks that specify the red, green, and blue components, respectively, of each pixel. 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 bitmap 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 (a bitmap in which the bitmap array immediately follows the BITMAPINFO header and which is referenced by a single pointer), the biClrUsed member must be set to an even number when using the DIB_PAL_COLORS mode so the DIB bitmap array starts on a doubleword boundary.

Note  The bmiColors member should not contain palette indices if the bitmap is to be stored in a file or transferred to another application. Unless the application has exclusive use and control of the bitmap, the bitmap color table should contain explicit RGB values.

See Also

BITMAPINFOHEADER, CreateDIBitmap, CreateDIBPatternBrush, CreateDIBSection, RGBQUAD


BITMAPINFOHEADER

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).

Members

biSize

Specifies the number of bytes required by the structure.

biWidth

Specifies the width of the bitmap, in pixels.

biHeight

Specifies the height of the bitmap, in pixels. If biHeight is positive, the bitmap is a bottom-up DIB and its origin is the lower left corner. If biHeight is negative, the bitmap is a top-down DIB and its origin is the upper left corner.

biPlanes

Specifies the number of planes for the target device. This value must be set to 1.

biBitCount

Specifies the number of bits per pixel. This value must be 1, 4, 8, 16, 24, or 32.

biCompression

Specifies the type of compression for a compressed bottom-up bitmap (top-down DIBs cannot be compressed). It can be one of the following values:

Value	Description
BI_RGB	An uncompressed format.
BI_RLE8	A run-length encoded (RLE) format for bitmaps with 8 bits per pixel. The compression format is a two-byte format consisting of a count byte followed by a byte containing a color index. For more information, see the following Remarks section.
BI_RLE4	An RLE format for bitmaps with 4 bits per pixel. The compression format is a two-byte format consisting of a count byte followed by two word-length color indices. For more information, see the following Remarks section.
BI_BITFIELDS	Specifies that the bitmap is not compressed and that the color table consists of three doubleword color masks that specify the red, green, and blue components, respectively, of each pixel. This is valid when used with 16- and 32-bits-per-pixel bitmaps.
biSizeImage

Specifies the size, in bytes, of the image. This may be set to 0 for BI_RGB bitmaps.

biXPelsPerMeter

Specifies the horizontal resolution, in pixels per meter, of the target device for the bitmap. An application can use this value to select a bitmap from a resource group that best matches the characteristics of the current device.

biYPelsPerMeter

Specifies the vertical resolution, in pixels per meter, of the target device for the bitmap.

biClrUsed

Specifies the number of color indices in the color table that are actually used by the bitmap. If this value is zero, the bitmap uses the maximum number of colors corresponding to the value of the biBitCount member for the compression mode specified by biCompression.

If biClrUsed is nonzero and the biBitCount member is less than 16, the biClrUsed member specifies the actual number of colors the graphics engine or device driver accesses. If biBitCount is 16 or greater, then biClrUsed member specifies the size of the color table used to optimize performance of Windows color palettes. If biBitCount equals 16 or 32, the optimal color palette starts immediately following the three doubleword masks.

If the bitmap is a packed bitmap (a bitmap in which the bitmap array immediately follows the BITMAPINFO header and which is referenced by a single pointer), the biClrUsed member must be either 0 or the actual size of the color table.

biClrImportant

Specifies the number of color indices that are considered important for displaying the bitmap. If this value is zero, all colors are important.

Remarks

The BITMAPINFO structure combines the BITMAPINFOHEADER structure and a color table to provide a complete definition of the dimensions and colors of a DIB. For more information about DIBs, see the description of the BITMAPINFO data structure.

An application should use the information stored in the biSize member to locate the color table in a BITMAPINFO structure, as follows:

pColor = ((LPSTR)pBitmapInfo +

    (WORD)(pBitmapInfo->bmiHeader.biSize));

Windows supports formats for compressing bitmaps that define their colors with eight or four bits per pixel. Compression reduces the disk and memory storage required for the bitmap. The following paragraphs describe these formats.

When the biCompression member is BI_RLE8, the bitmap is compressed by using a run-length encoding (RLE) format for an 8-bit bitmap. This format can be compressed in encoded or absolute modes. Both modes can occur anywhere in the same bitmap.

•	Encoded mode consists of two bytes: the first byte specifies the number of consecutive pixels to be drawn using the color index contained in the second byte. In addition, the first byte of the pair can be set to zero to indicate an escape that denotes an end of line, end of bitmap, or delta. The interpretation of the escape depends on the value of the second byte of the pair, which can be one of the following:

Value	Meaning
0	End of line.
1	End of bitmap.
2	Delta. The two bytes following the escape contain unsigned values indicating the horizontal and vertical offsets of the next pixel from the current position.
•	In absolute mode, the first byte is zero and the second byte is a value in the range 03H through FFH. The second byte represents the number of bytes that follow, each of which contains the color index of a single pixel. When the second byte is 2 or less, the escape has the same meaning as in encoded mode. In absolute mode, each run must be aligned on a word boundary.

The following example shows the hexadecimal values of an 8-bit compressed bitmap.

03 04 05 06 00 03 45 56 67 00 02 78 00 02 05 01

02 78 00 00 09 1E 00 01

This bitmap would expand as follows (two-digit values represent a color index for a single pixel):

04 04 04

06 06 06 06 06

45 56 67

78 78

move current position 5 right and 1 down

78 78

end of line

1E 1E 1E 1E 1E 1E 1E 1E 1E

end of RLE bitmap

When the biCompression member is BI_RLE4, the bitmap is compressed by using a run-length encoding format for a 4-bit bitmap, which also uses encoded and absolute modes:

•	In encoded mode, the first byte of the pair contains the number of pixels to be drawn using the color indices in the second byte. The second byte contains two color indices, one in its high-order four bits and one in its low-order four bits. The first of the pixels is drawn using the color specified by the high-order four bits, the second is drawn using the color in the low-order four bits, the third is drawn using the color in the high-order four bits, and so on, until all the pixels specified by the first byte have been drawn.

•	In absolute mode, the first byte is zero, the second byte contains the number of color indices that follow, and subsequent bytes contain color indices in their high- and low-order four bits, one color index for each pixel. In absolute mode, each run must be aligned on a word boundary. The end-of-line, end-of-bitmap, and delta escapes described for BI_RLE8 also apply to BI_RLE4 compression.

The following example shows the hexadecimal values of a 4-bit compressed bitmap.

03 04 05 06 00 06 45 56 67 00 04 78 00 02 05 01

04 78 00 00 09 1E 00 01

This bitmap would expand as follows (single-digit values represent a color index for a single pixel):

0 4 0

0 6 0 6 0

4 5 5 6 6 7

7 8 7 8

move current position 5 right and 1 down

7 8 7 8

end of line

1 E 1 E 1 E 1 E 1

end of RLE bitmap

If biHeight is negative, indicating a top-down DIB, biCompression must be either BI_RGB or BI_BITFIELDS. Top-down DIBs cannot be compressed.

See Also

BITMAPINFO


BITMAPV4HEADER  (preliminaryWindows 95)
BITMAPV4HEADER  (preliminary−Windows 95)

typedef struct {
    DWORD        bV4Size;
    LONG         bV4Width;
    LONG         bV4Height;
    WORD         bV4Planes;
    WORD         bV4BitCount;
    DWORD        bV4V4Compression;
    DWORD        bV4SizeImage;
    LONG         bV4XPelsPerMeter;
    LONG         bV4YPelsPerMeter;
    DWORD        bV4ClrUsed;
    DWORD        bV4ClrImportant;
    DWORD        bV4RedMask;
    DWORD        bV4GreenMask;
    DWORD        bV4BlueMask;
    DWORD        bV4AlphaMask;
    DWORD        bV4CSType;
    CIEXYZTRIPLE bV4Endpoints;
    DWORD        bV4GammaRed;
    DWORD        bV4GammaGreen;
    DWORD        bV4GammaBlue;
} BITMAPV4HEADER, FAR *LPBITMAPV4HEADER, *PBITMAPV4HEADER;

The BITMAPV4HEADER structure contains information about a Win32 version 4.0 bitmap.


BLOB

typedef struct _BLOB {

    ULONG   cbSize;

    BYTE    *pBlobData;

} BLOB;

A BLOB structure contains information about a block of data.

Members

cbSize

Specifies the size in bytes of the block of data pointed to by pBlobData

Addresses

Points to a block of data.

Remarks

The structure name BLOB comes from the acronym BLOB, which stands for "Binary Large OBject".

Note that this structure description says nothing about the nature of the data pointed to by pBlobData.

See Also

SERVICE_INFO


BROWSEINFO

typedef struct _browseinfo {

    HWND hwndOwner;          // see below

    LPCITEMIDLIST pidlRoot;  // see below

    LPSTR pszDisplayName;    // see below

    LPCSTR lpszTitle;        // see below

    UINT ulFlags;            // see below

    BFFCALLBACK lpfn;        // see below

    LPARAM lParam;           // see below

    int iImage;              // see below

} BROWSEINFO, *PBROWSEINFO, *LPBROWSEINFO;

Contains parameters for the the SHBrowseForFolder function and receives information about the folder selected by the user.

Members

hwndOwner

Handle of the owner window for the dialog box.

pidlRoot

Pointer to an item identifier list (an ITEMIDLIST structure) specifying the location of the "root" folder to browse from. Only the specified folder and its subfolders appear in the dialog box. This member can be NULL, and in that case, the name space root (the desktop folder) is used.

pszDisplayName

Pointer to a buffer that receives the display name of the folder selected by the user. The size of this buffer is assumed to be MAX_PATH bytes.

lpszTitle

Pointer to a null-terminated string that is displayed above the tree view control in the dialog box. This string can be used to specify instructions to the user.

ulFlags

Value specifying the types of folders to be listed in the dialog box as well as other options. This member can include zero or more of the following values:

BIF_BROWSEFORCOMPUTER	Only returns computers. If the user selects anything other than a computer, the OK button is grayed.
BIF_BROWSEFORPRINTER	Only returns printers. If the user selects anything other than a printer, the OK button is grayed.
BIF_DONTGOBELOWDOMAIN	Does not include network folders below the domain level in the tree view control.
BIF_RETURNFSANCESTORS	Only returns file system ancestors. If the user selects anything other than a file system ancestor, the OK button is grayed.
BIF_RETURNONLYFSDIRS	Only returns file system directories. If the user selects folders that are not part of the file system, the OK button is grayed.
BIF_STATUSTEXT	Includes a status area in the dialog box. The callback function can set the status text by sending messages to the dialog box.
lpfn

Address an application-defined function that the dialog box calls when events occur. For more information, see the description of the BrowseCallbackProc function. This member can be NULL.

lParam

Application-defined value that the dialog box passes to the callback function (if one is specified).

iImage

Variable that receives the image associated with the selected folder. The image is specified as an index to the system image list.

See Also

BrowseCallbackProc, ITEMIDLIST, SHBrowseForFolder


BY_HANDLE_FILE_INFORMATION

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.

Members

dwFileAttributes

Specifies file attributes. This member can be one or more of the following values:

Value	Meaning
FILE_ATTRIBUTE_ARCHIVE
	The file is an archive file. Applications use this value to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED
	The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY
	The file is a directory.
FILE_ATTRIBUTE_HIDDEN
	The file is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL
	The file has no other attributes. This value is valid only if used alone.
FILE_ATTRIBUTE_READONLY
	The file is read-only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM
	The file is part of the operating system or is used exclusively by it.
FILE_ATTRIBUTE_TEMPORARY
	The file is being used for temporary storage. Applications should write to the file only if absolutely necessary. Most of the file's data remains in memory without being flushed to the media because the file will soon be deleted.
ftCreationTime

Specifies the time the file was created. If the underlying file system does not support this time member, ftCreationTime is zero.

ftLastAccessTime

Specifies the time the file was last accessed. If the underlying file system does not support this time member, ftLastAccessTime is zero.

ftLastWriteTime

Specifies the last time the file was written to.

dwVolumeSerialNumber

Specifies the serial number of the volume that contains the file.

nFileSizeHigh

Specifies the high-order word of the file size.

nFileSizeLow

Specifies the low-order word of the file size.

nNumberOfLinks

Specifies the number of links to this file. For the FAT file system and HPFS, this member is always 1. For NTFS, it may be more than 1.

nFileIndexHigh

Specifies the high-order word of a unique identifier associated with the file.

nFileIndexLow

Specifies the low-order word of a unique identifier associated with the file. This identifier and the volume serial number uniquely identify a file. This number may change when the system is restarted or when the file is opened. After a process opens a file, the identifier is constant until the file is closed. An application can use this identifier and the volume serial number to determine whether two handles refer to the same file.

See Also

GetFileInformationByHandle


CANDIDATEFORM  (preliminaryWindows 95)
CANDIDATEFORM  (preliminary−Windows 95)

typedef _tagCANDIDATEFORM {
    DWORD  dwIndex;
    DWORD  dwStyle;
    POINT  ptCurrentPos;
    RECT   rcArea;
} CANDIDATEFORM;

The CANDIDATEFORM structure contains position information for the candidate window.

Members

dwIndex

Candidate list identifier. Can be 0 for the first list, 1 for the second, and so on. The maximum index is 31.

dwStyle

Position style. This member can be one of the following values:

CFS_CANDIDATEPOS	Display the upper-left corner of the candidate list window at the position given by ptCurrentPos. The coordinates are relative to the upper-left corner of the window containing the list window, and are subject to adjustment by the system.
CFS_EXCLUDE	Exclude the candidate window from the area given by rcArea. The ptCurrentPos member specifies the coordinates of the current point of interest, typically the caret position.
ptCurrentPos

Coordinates of the upper-left corner of the candidate window or the caret position, depending on the value of dwStyle.

rcArea

Coordinates of the upper-left and lower-right corners of the exclusion area.


CANDIDATELIST  (preliminaryWindows 95)
CANDIDATELIST  (preliminary−Windows 95)

typedef struct _tagCANDIDATELIST {
    DWORD  dwSize;
    DWORD  dwStyle;
    DWORD  dwCount;
    DWORD  dwSelection;
    DWORD  dwPageStart;
    DWORD  dwPageSize;
    DWORD  dwOffset[];
} CANDIDATELIST;

The CANDIDATELIST structure contains information about a candidate list.

Members

dwSize

Size, in bytes, of the structure, the offset array, and all candidate strings.

dwStyle

Candidate style values. This member can be one or more of the following values:

Value	Meaning
IME_CAND_UNKNOWN	Candidates are in a style other than listed here.
IME_CAND_READ	Candidates are in same reading.
IME_CAND_CODE	Candidates are in a code range.
IME_CAND_MEANING	Candidates are in same meaning.
IME_CAND_RADICAL	Candidates use same radical character.
IME_CAND_STROKES	Candidates are in same number of strokes.
For the IME_CAND_CODE style, the candidate list has a special structure depending on the value of the dwCount member. If dwCount is 1, the dwOffset member contains a single DBCS character rather than an offset, and no candidate string is provided. If the dwCount member is greater than 1, the dwOffset member contains valid offsets, and the candidate strings are text representations of individual DBCS character values in hexadecimal notation.

dwCount

Number of candidate strings.

dwSelection

Index of the selected candidate string.

dwPageStart

Index of the first candidate string in the candidate window. This varies as the user presses the PAGE UP and PAGE DOWN keys.

dwPageSize

Number of candidate strings to be shown in one page in the candidate window. The user can move to the next page by pressing IME-defined keys, such as the PAGE UP or PAGE DOWN key. If this number is zero, an application can define a proper value by itself.

dwOffset

Offset to the start of the first candidate string, relative to the start of this structure. The offsets for subsequent strings immediately follow this member, forming an array of 32-bit offsets.

Remarks

The candidate strings immediately follow the last offset in the dwOffset array.


CBT_CREATEWND

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.

Members

lpcs

Points to a CREATESTRUCT structure that contains initialization parameters for the window about to be created.

hwndInsertAfter

Identifies the window whose position in the Z order precedes that of the window being created.

See Also

CBTProc, CREATESTRUCT, SetWindowsHookEx


CBTACTIVATESTRUCT

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.

Members

fMouse

Specifies whether the window is being activated as a result of a mouse click. This value is TRUE if a mouse click is causing the activation or FALSE if it is not.

hWndActive

Identifies the active window.

See Also

SetWindowsHookEx


CHAR_INFO

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.

Members

Char

Specifies either the Unicode (wide-character) or ANSI character of a screen buffer character cell, depending on whether the Unicode or ANSI version of the function is used.

Attributes

Specifies the foreground (text) and background colors in which a screen buffer character cell is drawn. This member can be zero, or it can be any combination of the following values:

BACKGROUND_BLUE	FOREGROUND_BLUE
BACKGROUND_GREEN	FOREGROUND_GREEN
BACKGROUND_RED	FOREGROUND_RED
BACKGROUND_INTENSITY	FOREGROUND_INTENSITY
See Also

ReadConsoleOutput, ScrollConsoleScreenBuffer, WriteConsoleOutput


CHARFORMAT  (preliminaryWindows NT)
CHARFORMAT  (preliminary−Windows NT)

typedef struct _charformat {

    UINT     cbSize;

    _WPAD    _wPad1;

    DWORD    dwMask;

    DWORD    dwEffects;

    LONG     yHeight;

    LONG     yOffset;

    COLORREF crTextColor;

    BYTE     bCharSet;

    BYTE     bPitchAndFamily;

    TCHAR    szFaceName[LF_FACESIZE];

    _WPAD    _wPad2;

} CHARFORMAT;

The CHARFORMAT structure contains information about character formatting in a rich edit control.

Members

cbSize

Size in bytes of this structure. Must be set before passing the structure to the rich edit control.

dwMask

Members containing valid information or attributes to set. This member can be zero or more of the following values:

Value	Meaning
CFM_BOLD	The CFE_BOLD value of the dwEffects member is valid.
CFM_COLOR	The crTextColor member and the CFE_AUTOCOLOR value of the dwEffects member are valid.
CFM_FACE	The szFaceName member is valid.
CFM_ITALIC	The CFE_ITALIC value of the dwEffects member is valid.
CFM_OFFSET	The yOffset member is valid.
CFM_PROTECTED	The CFE_PROTECTED value of the dwEffects member is valid.
CFM_SIZE	The yHeight member is valid.
CFM_STRIKEOUT	The CFE_STRIKEOUT value of the dwEffects member is valid.
CFM_UNDERLINE.	The CFE_UNDERLINE value of the dwEffects member is valid.
dwEffects

Character effects. This member can be a combination of the following values:

Value	Meaning
CFE_AUTOCOLOR	The text color is the return value of GetSysColor (COLOR_WINDOWTEXT).
CFE_BOLD	Characters are bold.
CFE_ITALIC	Characters are italic.
CFE_STRIKEOUT	Characters are struck out.
CFE_UNDERLINE	Characters are underlined.
CFE_PROTECTED	Characters are protected; an attempt to modify them will cause an EN_PROTECTED notification message.
yHeight

Character height.

yOffset

Character offset from the baseline. If this member is positive, the character is a superscript; if it is negative, the character is a subscript.

crTextColor

Text color. This member is ignored if the CFE_AUTOCOLOR character effect is specified.

bCharSet

Character set value. Can be one of the values specified for the lfCharSet member of the LOGFONT structure.

bPitchAndFamily

Font family and pitch. This member is the same as the lfPitchAndFamily member of the LOGFONT structure.

szFaceName

Null-terminated character array specifying the font face name.

Remarks

This structure is used with the EM_GETCHARFORMAT and EM_SETCHARFORMAT messages.

See Also

GetSysColor, EM_GETCHARFORMAT, EM_SETCHARFORMAT, EN_PROTECTED, LOGFONT


CHARRANGE  (preliminaryWindows NT)
CHARRANGE  (preliminary−Windows NT)

typedef struct _charrange {

    LONG cpMin;

    LONG cpMax;

} CHARRANGE;

The CHARRANGE structure specifies a range of characters in a rich edit control. This structure is used with the EM_EXGETSEL and EM_EXSETSEL messages.

If the cpMin and cpMax members are equal, the range is empty. The range includes everything if cpMin is 0 and cpMax is  − 1.

Members

cpMin

Index of first intercharacter position.

cpMax

Index of last intercharacter position.

EM_EXGETSEL, EM_EXSETSEL


CHARSET

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.

Members

aflBlock

Specifies which (if any) of the 96 Unicode blocks are supported by a font. If the font contains at least one character in the given block, the corresponding bit is set.

flLang

Identifies the character set supported by the font. This member can be one of the following values:

Value	Meaning
CS_UGL	Supports the Universal Glyph List (UGL) character set.
CS_LATIN	Supports the Latin character set.
CS_GREEK	Supports the Greek character set.
CS_WIN30	Supports the Windows 3.0 character set.
Bits 0 and 31 of flLang are reserved and must be set to zero.


CHARSETINFO  (preliminaryWindows 95)
CHARSETINFO  (preliminary−Windows 95)

typedef struct {
    UINT ciCharset;
    UINT ciACP;
    FONTSIGNATURE fs;
} CHARSETINFO;

The CHARSETINFO structure contains information about a character set.

Members

ciCharset

Character set value.

ciACP

ANSI code-page value.

fs

A FONTSIGNATURE structure that identifies the Unicode and code-page font signature values. Only one Windows code-page will be set when this structure is set by the function.

See Also

FONTSIGNATURE, TranslateCharsetInfo


CHOOSECOLOR

typedef struct {   // cc

    DWORD        lStructSize;

    HWND         hwndOwner;

    HWND         hInstance;

    COLORREF     rgbResult;

    COLORREF*    lpCustColors;

    DWORD        Flags;

    LPARAM       lCustData;

    LPCCHOOKPROC lpfnHook;

    LPCTSTR      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.

Members

lStructSize

Specifies the length, in bytes, of the structure.

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

hInstance

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, the system selects the nearest solid color available if the CC_RGBINIT flag is specified in the Flags member and the value of this member is not among the colors available. If this member is NULL, the color initially selected is black.

lpCustColors

Points to an array of 16 doublewords that contain red, green, blue (RGB) values for the custom color boxes in the dialog box. If the user modifies these colors, the system updates the array with the new RGB values. 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 flags:

Flag	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 containing 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 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 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 Flags specifies the CC_ENABLETEMPLATE flag; otherwise, this member is ignored.

See Also

ChooseColor, MAKEINTRESOURCE, WM_INITDIALOG


CHOOSEFONT

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.

Members

lStructSize

Specifies the length, in bytes, of the structure.

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

hDC

Identifies the device context (or information context) of the printer whose fonts will be listed in the dialog box. This member is used only if the Flags member specifies the CF_PRINTERFONTS flag; otherwise, this member is ignored.

lpLogFont

Points to a LOGFONT structure. If an application initializes the members of this structure before calling the ChooseFont function and also sets the CF_INITTOLOGFONTSTRUCT flag, ChooseFont initializes the dialog box 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 flags:

Flag	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 specified, 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 only enumerate and allow the selection of TrueType fonts.
CF_EFFECTS	Specifies that ChooseFont should enable strikeout, underline, and color effects. If this flag is specified, the lfStrikOut, lfUnderline, and rgbColors members can be set before calling, and ChooseFont can use 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 the hInstance member identifies a data block that contains a dialog box template identified by the lpTemplateName member.
CF_ENABLETEMPLATEHANDLE	Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The system ignores the lpTemplateName member if this flag is specified.
CF_FIXEDPITCHONLY	Specifies that ChooseFont should select only fixed-pitch fonts.
CF_FORCEFONTEXIST	Specifies that ChooseFont should indicate an error condition if the user attempts to select a font or style that does not exist.
CF_INITTOLOGFONTSTRUCT	Specifies that ChooseFont should use the LOGFONT structure pointed to by the lpLogFont member to initialize the dialog box controls.
CF_LIMITSIZE	Specifies that ChooseFont should select only font sizes within the range specified by the nSizeMin and nSizeMax members.
CF_NOOEMFONTS	See the CF_NOVECTORFONTS description.
CF_NOFACESEL	Specifies that ChooseFont should not make an initial face name selection, because there is no one single face name that applies to the text selection. Set this flag if the text selection contains multiple face names.
CF_NOSCRIPTSEL	Windows 95 only: Specifies that there is no selection in the character set combo box. Applications use this flag to support multiple character set selections. This flag is set on input only. When it is set, the script combo box is disabled and the lfCharSet member of the LOGFONT structure is set to DEFAULT_CHARSET.
CF_NOSTYLESEL	Specifies that ChooseFont should not make an initial style selection, because there is no one single style that applies to the text selection. Set this flag if the text selection contains multiple styles.
CF_NOSIZESEL	Specifies that ChooseFont should not make an initial size selection, because there is no one single size that applies to the text selection. Set this flag if the text selection contains multiple sizes.
CF_NOSIMULATIONS	Specifies that ChooseFont should not allow graphics device interface (GDI) font simulations.
CF_NOVECTORFONTS	Specifies that ChooseFont should not allow vector font selections.
CF_NOVERTFONTS	Windows 95: Causes the Font dialog box to list only horizontally oriented fonts.
CF_PRINTERFONTS	Causes the dialog box to list only the fonts supported by the printer associated with the device context (or information context) identified by the hDC member.
CF_SCALABLEONLY	Specifies that ChooseFont should allow only the selection of scalable fonts. (Scalable fonts include vector fonts, scalable printer fonts, TrueType fonts, and fonts scaled by other technologies.)
CF_SCREENFONTS	Causes the dialog box to list only the screen fonts supported by the system.
CF_SCRIPTSONLY	Windows 95 only: Specifies that ChooseFont should allow selection of fonts for all non-OEM and Symbol character sets, as well as the ANSI character set. This supersedes the CF_ANSIONLY value.
CF_SELECTSCRIPT	Windows 95 only: When specified on input, only fonts with the character set identified in the lfCharSet member of the LOGFONT structure are displayed. The user will not be allowed to change the character set combo box.
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 specified, the CF_BOTH and CF_SCALABLEONLY flags should also be specified.
Windows 95: the CF_ANSIONLY flag is obsolete for Windows 95. To list ANSI fonts only, use the CF_SELSCRIPT value and set the IfCharSet member to ANSI_CHARSET.

rgbColors

If the CF_EFFECTS flag is specified, this member contains an RGB value that ChooseFont should use to specify 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 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 Flags specifies the CF_ENABLETEMPLATE flag; otherwise, this member is ignored.

hInstance

Identifies a data block that contains the dialog box template specified by lpstrTemplateName. This member is used only if Flags 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 specified, ChooseFont uses the data in this buffer to initialize the style control. When the user closes the dialog box, 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 following values:

Value	Meaning
SIMULATED_FONTTYPE	The font is simulated by the 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 specified.

nSizeMax

Specifies the maximum point size a user can select. ChooseFont recognizes this member only if the CF_LIMITSIZE flag is specified.

See Also

ChooseFont, MAKEINTRESOURCE


CIDA

typedef struct _IDA {

    UINT cidl;        // number array elements

    UINT aoffset[1];  // see below

} CIDA, * LPIDA;

This structure corresponds to the CF_IDLIST clipboard format.

Member

aoffset

Array of offsets relative to the beginning of the CIDA structure. The first element is the offset of the ITEMIDLIST structure for a folder (absolute from the root). Subsequent elements are offsets of ITEMIDLIST structures for file objects (relative from the parent folder).

See Also

ITEMIDLIST


CIEXYZ  (preliminaryWindows 95)
CIEXYZ  (preliminary−Windows 95)

typedef long FXPT2DOT30, FAR* LPFXPT2DOT30;  // fixed point 2.30

typedef struct tagCIEXYZ
{
    FXPT2DOT30 ciexyzX;

    FXPT2DOT30 ciexyzY;

    FXPT2DOT30 ciexyzZ;

} CIEXYZ;
typedef CIEXYZ FAR* LPCIEXYZ;

The CIEXYZ structure contains the x, y, and z coordinates of a specific color in a specified color space.

Members

ciexyzX

x coordinate in fix point (2.30).

ciexyzY

y coordinate in fix point (2.30).

ciexyzZ

z coordinate in fix point (2.30).


CIEXYZTRIPLE  (preliminaryWindows 95)
CIEXYZTRIPLE  (preliminary−Windows 95)

typedef struct tagCIEXYZTRIPLE
{
    CIEXYZ  ciexyzRed;

    CIEXYZ  ciexyzGreen;

    CIEXYZ  ciexyzBlue;

} CIEXYZTRIPLE;
typedef CIEXYZTRIPLE FAR* LPCIEXYZTRIPLE;

The CIEXYZTRIPLE structure contains the x, y, and z coordinates of the three colors that correspond to the red, green, blue endpoints for a specified logical color space.

Members

ciexyzRed;

xyz coordinates of red endpoint.

ciexyzGreen

xyz coordinates of green endpoint.

ciexyzBlue

xyz coordinates of blue endpoint.


CLIENTCREATESTRUCT

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.

Members

hWindowMenu

Identifies the handle of the MDI application's Window menu. An MDI application can retrieve this handle from the menu of the MDI frame window by using the GetSubMenu function.

idFirstChild

Specifies the child window identifier of the first MDI child window created. Windows increments the identifier for each additional MDI child window the application creates, and reassigns identifiers when the application destroys a window to keep the range of identifiers contiguous. These identifiers are used in WM_COMMAND messages sent to the application's MDI frame window when a child window is chosen from the Window menu; they should not conflict with any other command identifiers.

See Also

CreateWindow, GetSubMenu, MDICREATESTRUCT, WM_COMMAND


CMINVOKECOMMANDINFO

typedef struct _CMInvokeCommandInfo {

    DWORD cbSize;        // sizeof(CMINVOKECOMMANDINFO)

    DWORD fMask;         // see below

    HWND hwnd;           // see below

    LPCSTR lpVerb;       // see below

    LPCSTR lpParameters; // see below

    LPCSTR lpDirectory;  // see below

    int nShow;           // see below

    DWORD dwHotKey;      // see below

    HANDLE hIcon;        // see below

} CMINVOKECOMMANDINFO, *LPCMINVOKECOMMANDINFO;

Contains information about a context menu command.

Members

fMask

Value specifying zero or more of the following flags:

CMIC_MASK_HOTKEY	Specifies that the dwHotKey member is valid.
CMIC_MASK_ICON	Specifies that the hIcon member is valid.
CMIC_MASK_FLAG_NO_UI	Prevents the system from displaying user interface elements (for example, error messages) while carrying out a command.
hwnd

Handle of the window that owned the context menu, such as the desktop, the explorer, or the tray. An extension might specify this handle as the owner window of any message boxes or dialog boxes it displays.

lpVerb

32-bit value containing zero in the high-order word and the menu-identifier offset of the command to carry out in the low-order word. The shell specifies this value (using the MAKEINTRESOURCE macro) when the user chooses a menu command.

If the high-order word is not zero, this member is the address of a null-terminated string specifying the language-independent name of the command to carry out. This member is typically a string when a command is being activated by an application. The system provides predefined constant values for the following command strings:

Value	String
CMDSTR_NEWFOLDER	"NewFolder"
CMDSTR_VIEWDETAIL	"ViewDetails"
CMDSTR_VIEWLIST	"ViewList"
lpParameters

Optional parameters. This member is always NULL for menu items inserted by a shell extension.

lpDirectory

Optional working directory name. This member is always NULL for menu items inserted by a shell extension.

nShow

Flag to pass to the ShowWindow function if the command displays a window or starts an application.

dwHotKey

Optional hot key to assign any application activated by the command. If fMask does not specify CMIC_MASK_HOTKEY, this member is ignored.

hIcon

Icon to use for any application activated by the command. If the fMask member does not specify CMIC_MASK_ICON, this member is ignored.

Remarks

The address of this structure is passed to the IContextMenu::InvokeCommand method.

See Also

IContextMenu::InvokeCommand, MAKEINTRESOURCE, ShowWindow


COLORADJUSTMENT

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 stretch mode is HALFTONE.

Members

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 type of standard light source under which the image is viewed. This member may be set to one of the following values:

Value	Meaning
ILLUMINANT_DEVICE_DEFAULT	Device's default. Standard used by output devices.
ILLUMINANT_A	Tungsten lamp.
ILLUMINANT_B	Noon sunlight.
ILLUMINANT_C	NTSC daylight.
ILLUMINANT_D50	Normal print.
ILLUMINANT_D55	Bond paper print.
ILLUMINANT_D65	Standard daylight. Standard for CRTs and pictures.
ILLUMINANT_D75	Northern daylight.
ILLUMINANT_F2	Cool white lamp
ILLUMINANT_TUNGSTEN	Same as ILLUMINANT_A.
ILLUMINANT_DAYLIGHT	Same as ILLUMINANT_C.
ILLUMINANT_FLUORESCENT	Same as ILLUMINANT_F2.
ILLUMINANT_NTSC	Same as ILLUMINANT_C.
caRedGamma

Specifies the nth power gamma-correction value for the red primary of the source colors. The value must be in the range from 2500 to 65,000. A value of 10,000 means no gamma-correction.

caGreenGamma

Specifies the nth power gamma-correction value for the green primary of the source colors. The value must be in the range from 2500 to 65,000. A value of 10,000 means no gamma-correction.

caBlueGamma

Specifies the nth power gamma-correction value for the blue primary of the source colors. The value must be in the range from 2500 to 65,000. A value of 10,000 means no gamma-correction.

caReferenceBlack

Specifies the black reference for the source colors. Any colors that are darker than this are treated as black. The value must be in the range from 0 to 4000.

caReferenceWhite

Specifies the white reference for the source colors. Any colors that are lighter than this are treated as white. The value must be in the range from 6000 to 10,000.

caContrast

Specifies the amount of contrast to be applied to the source object. The value must be in the range from  − 100 to 100. A value of 0 means no contrast adjustment.

caBrightness

Specifies the amount of brightness to be applied to the source object. The value must be in the range from  − 100 to 100. A value of 0 means no brightness adjustment.

caColorfulness

Specifies the amount of colorfulness to be applied to the source object. The value must be in the range from  − 100 to 100. A value of 0 means no colorfulness adjustment.

caRedGreenTint

Specifies the amount of red or green tint adjustment to be applied to the source object. The value must be in the range from  − 100 to 100. Positive numbers adjust towards red and negative numbers adjust towards green. Zero means no tint adjustment.

See Also

SetStretchBltMode, StretchBlt, StretchDIBits


COLORMAP  (preliminaryWindows NT)
COLORMAP  (preliminary−Windows NT)

typedef struct _COLORMAP {

    COLORREF from;

    COLORREF to;

} COLORMAP, FAR* LPCOLORMAP;

The COLORMAP structure contains information used by the CreateMappedBitmap function to map the colors of the bitmap.

Members

from

Color to map from.

to

Color to map to.

See Also

CreateMappedBitmap


COLORREF

The COLORREF value is a 32-bit value used to specify an RGB color.

Remarks

When specifying an explicit RGB color, the COLORREF value has the following hexadecimal form:

0x00bbggrr

The low-order byte contains a value for the relative intensity of red; the second byte contains a value for green; and the third byte contains a value for blue. The high-order byte must be zero. The maximum value for a single byte is 0xFF.

See Also

GetBValue, GetGValue, GetRValue, RGB


COMMCONFIG  (preliminaryWindows 95)
COMMCONFIG  (preliminary−Windows 95)

typedef struct _COMM_CONFIG {
    DWORD dwSize;
    WORD  wVersion;

    WORD  wReserved;
    DCB   dcb;
    DWORD dwProviderSubType;
    DWORD dwProviderOffset;
    DWORD dwProviderSize;
    WCHAR wcProviderData[1];
} COMMCONFIG, *LPCOMMCONFIG;

The COMMCONFIG structure contains information about the configuration state of a communications device.

Members

dwSize

Specifies the size, in bytes, of the COMMCONFIG structure.

wVersion

Specifies the version number of the COMMCONFIG structure. For
Windows 95 device drivers, this parameter can be 1. The version of the provider-specific structure should be included in the wcProviderData member.

wReserved

Reserved; do not use.

dcb

Specifies a device-control block (DCB) structure for RS-232 serial devices. A DCB structure is always present regardless of the port driver subtype specified in the device's COMMPROP structure.

dwProviderSubType

Identifies the type of communications provider, and thus the format of the provider-specific data. For a list of communications provider types, see the description of the COMMPROP structure.

dwProviderOffset

Specifies the offset, in bytes, of the provider-specific data relative to the beginning of the structure. This member is zero if there is no provider-specific data.

dwProviderSize

Specifies the size, in bytes, of the provider-specific data.

wcProviderData

Contains the provider-specific data, if any. This member may be of any size or may be omitted. Because the COMMCONFIG structure may be expanded in the future, applications should use the dwProviderOffset member to determine the location of this member.

Remarks

If the provider subtype is PST_RS232 or PST_PARALLELPORT the wcProviderData member is omitted. If the provider subtype is PST_MODEM, the wcProviderData member contains a MODEMSETTINGS structure.

See Also

DCB, COMMPROP, GetCommProperties, MODEMSETTINGS


COMMPROP

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 by the GetCommProperties function to return information about a given communications driver.

Members

wPacketLength

Specifies the size, in bytes, of the entire data packet, regardless of the amount of data requested.

wPacketVersion

Specifies the version of the structure.

dwServiceMask

Specifies a bitmask indicating which services are implemented by this provider. The SP_SERIALCOMM value is always specified for communications providers, including modem providers.

dwReserved1

Reserved; do not use.

dwMaxTxQueue

Specifies the maximum size, in bytes, of the driver's internal output buffer. A value of zero indicates that no maximum value is imposed by the serial provider.

dwMaxRxQueue

Specifies the maximum size, in bytes, of the driver's internal input buffer. A value of zero indicates that no maximum value is imposed by the serial provider.

dwMaxBaud

Specifies the maximum allowable baud rate, in bits per second (bps). This member can be one of the following values:

Value	Meaning
BAUD_075	75 bps
BAUD_110	110 bps
BAUD_134_5	134.5 bps
BAUD_150	150 bps
BAUD_300	300 bps
BAUD_600	600 bps
BAUD_1200	1200 bps
BAUD_1800	1800 bps
BAUD_2400	2400 bps
BAUD_4800	4800 bps
BAUD_7200	7200 bps
BAUD_9600	9600 bps
BAUD_14400	14400 bps
BAUD_19200	19200 bps
BAUD_38400	38400 bps
BAUD_56K	56K bps
BAUD_57600	57600 bps
BAUD_115200	115200 bps
BAUD_128K	128K bps
BAUD_USER	Programmable baud rates available
dwProvSubType

Specifies the specific communications provider type:

Value	Meaning
PST_FAX	FAX device
PST_LAT	LAT protocol
PST_MODEM	Modem device
PST_NETWORK_BRIDGE	Unspecified network bridge
PST_PARALLELPORT	Parallel port
PST_RS232	RS-232 serial port
PST_RS422	RS-422 port
PST_RS423	RS-423 port
PST_RS449	RS-449 port
PST_SCANNER	Scanner device
PST_TCPIP_TELNET	TCP/IP Telnet® protocol
PST_UNSPECIFIED	Unspecified
PST_X25	X.25 standards
dwProvCapabilities

Specifies a bitmask indicating the capabilities offered by the provider. This member can be one of the following values:

Value	Meaning
PCF_16BITMODE	Special 16-bit mode supported
PCF_DTRDSR	DTR (data-terminal-ready)/DSR (data-set-ready) supported
PCF_INTTIMEOUTS	Interval time-outs supported
PCF_PARITY_CHECK	Parity checking supported
PCF_RLSD	RLSD (receive-line-signal-detect) supported
PCF_RTSCTS	RTS (request-to-send)/CTS (clear-to-send) supported
PCF_SETXCHAR	Settable XON/XOFF supported
PCF_SPECIALCHARS	Special character support provided
PCF_TOTALTIMEOUTS	Total (elapsed) time-outs supported
PCF_XONXOFF	XON/XOFF flow control supported
dwSettableParams

Specifies a bitmask indicating the communications parameter that can be changed. This member can be one of the following values:

Value	Meaning
SP_BAUD	Baud rate
SP_DATABITS	Data bits
SP_HANDSHAKING	Handshaking (flow control)
SP_PARITY	Parity
SP_PARITY_CHECK	Parity checking
SP_RLSD	RLSD (receive-line-signal-detect)
SP_STOPBITS	Stop bits
dwSettableBaud

Specifies a bitmask indicating the baud rates that can be used. For values, see the dwMaxBaud member.

wSettableData

Specifies a bitmask indicating the number of data bits that can be set. This member can be one of the following values:

Value	Meaning
DATABITS_5	5 data bits
DATABITS_6	6 data bits
DATABITS_7	7 data bits
DATABITS_8	8 data bits
DATABITS_16	16 data bits
DATABITS_16X	Special wide path through serial hardware lines
wSettableStopParity

Specifies a bitmask indicating the stop bit and parity settings that can be selected. This member can be one of the following values:

Value	Meaning
STOPBITS_10	1 stop bit
STOPBITS_15	1.5 stop bits
STOPBITS_20	2 stop bits
PARITY_NONE	No parity
PARITY_ODD	Odd parity
PARITY_EVEN	Even parity
PARITY_MARK	Mark parity
PARITY_SPACE	Space parity
dwCurrentTxQueue

Specifies the size, in bytes, of the driver's internal output buffer. A value of zero indicates that the value is unavailable.

dwCurrentRxQueue

Specifies the size, in bytes, of the driver's internal input buffer. A value of zero indicates that the value is unavailable.

dwProvSpec1

Specifies provider-specific data. Applications should ignore this member unless they have detailed information about the format of the data required by the provider.

Windows 95 only: Set this member to COMMPROP_INITIALIZED before calling the GetCommProperties function to indicate that the wPacketLength member is already valid.

dwProvSpec2

Specifies provider-specific data. Applications should ignore this member unless they have detailed information about the format of the data required by the provider.

wcProvChar

Specifies provider-specific data. Applications should ignore this member unless they have detailed information about the format of the data required by the provider.

Remarks

The contents of the dwProvSpec1, dwProvSpec2, and wcProvChar members depend on the provider subtype (specified by the dwProvSubType member).

Windows 95 only:

If the provider subtype is PST_MODEM, these members are used as follows:

Value	Meaning
dwProvSpec1	Not used.
dwProvSpec2	Not used.
wcProvChar	Contains a MODEMDEVCAPS structure.
See Also

GetCommProperties


COMMTIMEOUTS

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 time-out parameters for a communications device. The parameters determine the behavior of ReadFile, WriteFile, ReadFileEx, and WriteFileEx operations on the device.

Members

ReadIntervalTimeout

Specifies the maximum time, in milliseconds, allowed to elapse between the arrival of two characters on the communications line. During a ReadFile operation, the time period begins when the first character is received. If the interval between the arrival of any two characters exceeds this amount, the ReadFile operation is completed and any buffered data is returned. A value of zero indicates that interval time-outs are not used.

A value of MAXDWORD, combined with zero values for both the ReadTotalTimeoutConstant and ReadTotalTimeoutMultiplier members, specifies that the read operation is to return immediately with the characters that have already been received, even if no characters have been received.

ReadTotalTimeoutMultiplier

Specifies the multiplier, in milliseconds, used to calculate the total time-out period for read operations. For each read operation, this value is multiplied by the requested number of bytes to be read.

ReadTotalTimeoutConstant

Specifies the constant, in milliseconds, used to calculate the total time-out period for read operations. For each read operation, this value is added to the product of the ReadTotalTimeoutMultiplier member and the requested number of bytes.

A value of zero for both the ReadTotalTimeoutMultiplier and ReadTotalTimeoutConstant members indicates that total time-outs are not used for read operations.

WriteTotalTimeoutMultiplier

Specifies the multiplier, in milliseconds, used to calculate the total time-out period for write operations. For each write operation, this value is multiplied by the number of bytes to be written.

WriteTotalTimeoutConstant

Specifies the constant, in milliseconds, used to calculate the total time-out period for write operations. For each write operation, this value is added to the product of the WriteTotalTimeoutMultiplier member and the number of bytes to be written.

A value of zero for both the WriteTotalTimeoutMultiplier and WriteTotalTimeoutConstant members indicates that total time-outs are not used for write operations.

Remarks

Windows 95: If an application sets the ReadIntervalTimeout and readTotalTimeoutMultiplier members to MAXDWORD and the ReadTotalTimeoutConstant member to a value greater than zero and less than MAXDWORD, one of the following occurs when the readFile function is called:Selecting a button typically causes the following events:

•	If there are any characters in the input buffer, ReadFile returns immediately with the characters in the buffer.

•	If there are no characters in the input buffer, ReadFile waits until a character arrives and then returns immediately.

•	If no character arrives within the time specified by the ReadTotalTimeoutConstant member, ReadFile times out.

See Also

GetCommTimeouts, ReadFile, ReadFileEx, SetCommTimeouts, WriteFile, WriteFileEx


COMPAREITEMSTRUCT

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-drawn list box or combo box.

Whenever an application adds a new item to an owner-drawn list box or combo box created with the CBS_SORT or LBS_SORT style, Windows sends the owner a WM_COMPAREITEM message. The lParam parameter of the message contains a long pointer to a COMPAREITEMSTRUCT structure. Upon receiving the message, the owner compares the two items and returns a value indicating which item sorts before the other.

Members

CtlType

Specifies ODT_LISTBOX (an owner-drawn list box) or ODT_COMBOBOX (an owner-drawn combo box).

CtlID

Specifies the identifier of the list box or combo box.

hwndItem

Identifies the control.

itemID1

Specifies the index of the first item in the list box or combo box being compared.

itemData1

Specifies application-supplied data for the first item being compared. (This value was passed as the lParam parameter of the message that added the item to the list box or combo box.)

itemID2

Specifies the index of the second item in the list box or combo box being compared.

itemData2

Specifies application-supplied data for the second item being compared. This value was passed as the lParam parameter of the message that added the item to the list box or combo box.

See Also

WM_COMPAREITEM


COMPOSITIONFORM  (preliminaryWindows 95)
COMPOSITIONFORM  (preliminary−Windows 95)

typedef _tagCOMPOSITIONFORM {
    DWORD  dwStyle;
    POINT  ptCurrentPos;
    RECT   rcArea;
} COMPOSITIONFORM;

The COMPOSITIONFORM structure contains position information for the composition window.

Members

dwStyle

Position style. This member can be one of the following values:

Value	Meaning
CFS_DEFAULT	Move the composition window to the default position. The IME window can display the composition window outside the client area, such as in a floating window.
CFS_FORCE_POSITION	Display the upper-left corner of the composition window at exactly the position given by ptCurrentPos. The coordinates are relative to the upper-left corner of the window containing the composition window and are not subject to adjustment by the IME.
CFS_POINT	Display the upper-left corner of the composition window at the position given by ptCurrentPos. The coordinates are relative to the upper-left corner of the window containing the composition window and are subject to adjustment by the IME.
CFS_RECT	Display the composition window at the position given by rcArea. The coordinates are relative to the upper-left of the window containing the composition window.
ptCurrentPos

Coordinates of the upper-left corner of the composition window.

rcArea

Coordinates of the upper-left and lower-right corners of the composition window.

Remarks

Some IME windows adjust the composition window position specified by the system or the application. The CFS_FORCE_POSITION directs the IME window to skip this adjustment.


COMSTAT

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 by the ClearCommError function.

Members

fCtsHold

Specifies whether transmission is waiting for the CTS (clear-to-send) signal to be sent. If this member is TRUE, transmission is waiting.

fDsrHold

Specifies whether transmission is waiting for the DSR (data-set-ready) signal to be sent. If this member is TRUE, transmission is waiting.

fRlsdHold

Specifies whether transmission is waiting for the RLSD (receive-line-signal-detect) signal to be sent. If this member is TRUE, transmission is waiting.

fXoffHold

Specifies whether transmission is waiting because the XOFF character was received. If this member is TRUE, transmission is waiting.

fXoffSent

Specifies whether transmission is waiting because the XOFF character was transmitted. If this member is TRUE, transmission is waiting. Transmission halts when the XOFF character is transmitted to a system that takes the next character as XON, regardless of the actual character.

fEof

Specifies whether the end-of-file (EOF) character has been received. If this member is TRUE, the EOF character has been received.

fTxim

If this member is TRUE, there is a character queued for transmission that has come to the communications device by way of the TransmitCommChar function. The communications device transmits such a character ahead of other characters in the device's output buffer.

fReserved

Reserved; do not use.

cbInQue

Specifies the number of bytes received by the serial provider but not yet read by a ReadFile operation.

cbOutQue

Specifies the number of bytes of user data remaining to be transmitted for all write operations. This value will be zero for a nonoverlapped write.

See Also

ClearCommError, ReadFile, TransmitCommChar


CONSOLE_CURSOR_INFO

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.

Members

dwSize

Specifies a number between 1 and 100, indicating the percentage of the character cell that is filled by the cursor. The cursor appearance varies, ranging from completely filling the cell to showing up as a horizontal line at the bottom of the cell.

bVisible

Specifies the visibility of the cursor. If the cursor is visible, this member is TRUE.

See Also

GetConsoleCursorInfo, SetConsoleCursorInfo


CONSOLE_SCREEN_BUFFER_INFO

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.

Members

dwSize

Specifies the size, in character columns and rows, of the screen buffer.

dwCursorPosition

Specifies the column and row coordinates of the cursor in the screen buffer.

wAttributes

Specifies the foreground (text) and background color attributes to be used for characters that are written to a screen buffer by the WriteFile and WriteConsole functions, or echoed to a screen buffer by the ReadFile and ReadConsole functions. The attribute values are some combination of the following values: FOREGROUND_BLUE, FOREGROUND_GREEN, FOREGROUND_RED, FOREGROUND_INTENSITY, BACKGROUND_BLUE, BACKGROUND_GREEN, BACKGROUND_RED, and BACKGROUND_INTENSITY. For example, the following combination of values produces red text on a white background:

FOREGROUND_RED | BACKGROUND_RED | BACKGROUND_GREEN | BACKGROUND_BLUE

srWindow

Specifies a SMALL_RECT structure that contains the screen buffer coordinates of the upper-left and lower-right corners of the display window.

dwMaximumWindowSize

Specifies the maximum size of the console window, given the current screen buffer size and font and the screen size.

See Also

GetConsoleScreenBufferInfo, ReadConsole, ReadFile, SMALL_RECT, WriteConsole, WriteFile


CONTEXT

A CONTEXT structure contains processor-specific register data. The Windows NT operating system uses CONTEXT structures to perform various internal operations. Currently, there are CONTEXT structures defined for Intel®, MIPS®,  Alpha®, and PowerPC®,processors. Refer to the header file WinNT.h for definitions of these structures.


CONVCONTEXT

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 DDE client application. The information is useful for specialized or cross-language DDE conversations.

Members

cb

Specifies the structure's size, in bytes.

wFlags

Specifies conversation context flags. Currently, no flags are defined for this member.

wCountryID

Specifies the country-code identifier for topic-name and item-name strings.

iCodePage

Specifies the code page for topic-name and item-name strings. Non-multilingual clients should set this member to CP_WINANSI. Unicode clients should set this value to CP_WINUNICODE.

dwLangID

Specifies the language identifier for topic-name and item-name strings.

dwSecurity

Specifies a private (application-defined) security code.

qos

Specifies the quality of service a DDE client wants from the system during a given conversation. The quality of service level specified lasts for the duration of the conversation. It cannot be changed once the conversation is started.


CONVINFO

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 DDE conversation.

Members

cb

Specifies the structure's size, in bytes.

hUser

Identifies application-defined data.

hConvPartner

Identifies the partner application in the DDE conversation. This member is zero if the partner has not registered itself (using the DdeInitialize function) to make DDE Management Library (DDEML) function calls. An application should not pass this member to any DDEML function except DdeQueryConvInfo.

hszSvcPartner

Identifies the service name of the partner application.

hszServiceReq

Identifies the service name of the server application that was requested for connection.

hszTopic

Identifies the name of the requested topic.

hszItem

Identifies the name of the requested item. This member is transaction specific.

wFmt

Specifies the format of the data being exchanged. This member is transaction specific.

wType

Specifies the type of the current transaction. This member is transaction specific; it can be one of the following values:

Value	Meaning
XTYP_ADVDATA	Informs a client that advise data from a server has arrived.
XTYP_ADVREQ	Requests a server to send updated data to the client during an advise loop. This transaction results when the server calls DdePostAdvise.
XTYP_ADVSTART	Requests a server to begin an advise loop with a client.
XTYP_ADVSTOP	Notifies a server that an advise loop is stopping.
XTYP_CONNECT	Requests a server to establish a conversation with a client.
XTYP_CONNECT_CONFIRM	Notifies a server that a conversation with a client has been established.
XTYP_DISCONNECT	Notifies a server that a conversation has terminated.
XTYP_EXECUTE	Requests a server to execute a command sent by a client.
XTYP_MONITOR	Notifies an application registered as APPCMD_MONITOR that DDE data is being transmitted.
XTYP_POKE	Requests a server to accept unsolicited data from a client.
XTYP_REGISTER	Notifies other DDEML applications that a server has registered a service name.
XTYP_REQUEST	Requests a server to send data to a client.
XTYP_UNREGISTER	Notifies other DDEML applications that a server has unregistered a service name.
XTYP_WILDCONNECT	Requests a server to establish multiple conversations with the same client.
XTYP_XACT_COMPLETE	Notifies a client that an asynchronous data transaction has been completed.
wStatus

Specifies the status of the current conversation. This member can be a combination of the following values:

Value	Meaning
ST_ADVISE	One or more links are in progress.
ST_BLOCKED	The conversation is blocked.
ST_BLOCKNEXT	The conversation will block after calling the next callback.
ST_CLIENT	The conversation handle passed to the DdeQueryConvInfo function is a client-side handle. If the handle is zero, the conversation handle passed to the DdeQueryConvInfo function is a server-side handle.
ST_CONNECTED	The conversation is connected.
ST_INLIST	The conversation is a member of a conversation list.
ST_ISLOCAL	Both sides of the conversation are using the DDEML.
ST_ISSELF	Both sides of the conversation are using the same instance of the DDEML.
ST_TERMINATED	The conversation has been terminated by the partner.
wConvst

Specifies the conversation state. This member can be one of the following values:

Value	Meaning
XST_ADVACKRCVD	The advise transaction has just been completed.
XST_ADVDATAACKRCVD	The advise data transaction has just been completed.
XST_ADVDATASENT	Advise data has been sent and is awaiting an acknowledgement.
XST_ADVSENT	An advise transaction is awaiting an acknowledgement.
XST_CONNECTED	The conversation has no active transactions.
XST_DATARCVD	The requested data has just been received.
XST_EXECACKRCVD	An execute transaction has just been completed.
XST_EXECSENT	An execute transaction is awaiting an acknowledgement.
XST_INCOMPLETE	The last transaction failed.
XST_INIT1	Mid-initiate state 1.
XST_INIT2	Mid-initiate state 2.
XST_NULL	Pre-initiate state.
XST_POKEACKRCVD	A poke transaction has just been completed.
XST_POKESENT	A poke transaction is awaiting an acknowledgement.
XST_REQSENT	A request transaction is awaiting an acknowledgement.
XST_UNADVACKRCVD	An unadvise transaction has just been completed.
XST_UNADVSENT	An unadvise transaction is awaiting an acknowledgement.
wLastError

Specifies the error value associated with the last transaction.

hConvList

Identifies the conversation list if the handle of the current conversation is in a conversation list. This member is NULL if the conversation is not in a conversation list.

ConvCtxt

Specifies the conversation context.

hwnd

Identifies the window of the calling application involved in the conversation.

hwndPartner

Identifies the window of the partner application involved in the current conversation.

See Also

CONVCONTEXT, DdeInitialize, DdePostAdvise, DdeQueryConvInfo


COORD

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.

Members

X

Horizontal or column value.

Y

Vertical or row value.


COPYDATASTRUCT

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.

Members

dwData

Specifies up to 32 bits of data to be passed to the receiving application.

cbData

Specifies the size, in bytes, of the data pointed to by the lpData member.

lpData

Points to data to be passed to the receiving application. This member can be NULL.

See Also

WM_COPYDATA


CPINFO

struct _cpinfo {

    UINT MaxCharSize;

    BYTE DefaultChar[MAX_DEFAULTCHAR];

    BYTE LeadByte[MAX_LEADBYTES];

} CPINFO;

The CPINFO structure contains information about a code page.

Members

MaxCharSize

Specifies the maximum length, in bytes, of a character in this code page.

DefaultChar

Specifies the default character used in translations into this code page. This character is used by the WideCharToMultiByte function if an explicit default character is not given.

LeadByte

Specifies a fixed-length array of lead-byte ranges, where the number of lead-byte ranges is variable. If there are no lead bytes in this code page, then every element of the array is NULL. If there are lead bytes in this code page, a starting value and ending value is given for each range. Ranges are inclusive. The maximum number of lead-byte ranges for any code page is 5. The array uses two bytes to describe each range, with a double-byte null terminator after the last range.

Remarks

Lead bytes are unique to double-byte character sets (DBCS). A lead byte is the first byte of a 2-byte character in a DBCS. Lead bytes occupy a specific range of byte values.

See Also

GetCPInfo, WideCharToMultiByte


CPLINFO

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 dialog box supported by a Control Panel application.

Members

idIcon

Specifies the resource identifier of the icon that represents the dialog box.

idName

Specifies the resource identifier of the string containing the short name for the dialog box. This name is intended to be displayed below the icon.

idInfo

Specifies the resource identifier of the string containing the description for the dialog box. The description is the descriptive string that is intended to be displayed when the application icon is selected.

lData

Specifies user-defined data for the dialog box.

See Also

CPL_NEWINQUIRE, NEWCPLINFO


CREATE_PROCESS_DEBUG_INFO

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.

Members

hFile

Identifies an open handle of the process's image file. If this member is NULL, the handle is not valid. Otherwise, the debugger can use the member to read from and write to the image file.

hProcess

Identifies an open handle of the process. If this member is NULL, the handle is not valid. Otherwise, the debugger can use the member to read from and write to the process's memory.

hThread

Identifies an open handle of the initial thread of the process identified by the hProcess member. If hThread is NULL, the handle is not valid. Otherwise, the debugger has THREAD_GET_CONTEXT, THREAD_SET_CONTEXT, and THREAD_SUSPEND_RESUME access to the thread, allowing the debugger to read from and write to the registers of the thread and to control execution of the thread.

lpBaseOfImage

Points to the base address of the executable image that the process is running.

dwDebugInfoFileOffset

Specifies the offset to the debugging information in the file identified by the hFile member. The kernel expects the debugging information to be in Microsoft® CodeView® version 4.0 format. This format is currently a derivative of COFF (Common Object File Format).

nDebugInfoSize

Specifies the size, in bytes, of the debugging information in the file. If this value is zero, there is no debugging information.

lpThreadLocalBase

Points to a block of data. At offset 0x2C into this block is another pointer, called ThreadLocalStoragePointer, that points to an array of per-module thread local storage blocks. This gives a debugger access to per-thread data in the threads of the process being debugged using the same algorithms that a compiler would use.

lpStartAddress

Points to the starting address of the thread. This value may only be an approximation of the thread's starting address, because any application with appropriate access to the thread can change the thread's context by using the SetThreadContext function.

lpImageName

Points to the filename associated with the hFile parameter. This parameter may be NULL, or it may contain the address of a string pointer in the address space of the process being debugged. That address may, in turn, either be NULL or point to the actual filename. If fUnicode is a nonzero value, the name string is Unicode; otherwise, it is ANSI.

This member is strictly optional. Debuggers must be prepared to handle the case where lpImageName is NULL or *lpImageName (in the address space of the process being debugged) is NULL. Specifically, Windows does not provide an image name for a create process event, and will not likely pass an image name for the first DLL event. Windows also does not provide this information in the case of debug events that originate from a call to the DebugActiveProcess function.

fUnicode

Indicates whether a file name specified by the lpImageName member is Unicode or ANSI. A nonzero value indicates Unicode; zero indicates ANSI.

See Also

CREATE_THREAD_DEBUG_INFO, DebugActiveProcess, DEBUG_EVENT, LOAD_DLL_DEBUG_INFO, SetThreadContext


CREATE_THREAD_DEBUG_INFO

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.

Members

hThread

Identifies a handle of the thread whose creation caused the debugging event. If this member is NULL, the handle is not valid. Otherwise, the debugger has THREAD_GET_CONTEXT, THREAD_SET_CONTEXT, and THREAD_SUSPEND_RESUME access to the thread, allowing the debugger to read from and write to the registers of the thread and control execution of the thread.

lpThreadLocalBase

Points to a block of data. At offset 0x2C into this block is another pointer, called ThreadLocalStoragePointer, that points to an array of per-module thread local storage blocks. This gives a debugger access to per-thread data in the threads of the process being debugged using the same algorithms that a compiler would use.

lpStartAddress

Points to the starting address of the thread. This value may only be an approximation of the thread's starting address, because any application with appropriate access to the thread can change the thread's context by using the SetThreadContext function.

See Also

CREATE_PROCESS_DEBUG_INFO, DEBUG_EVENT, LOAD_DLL_DEBUG_INFO, SetThreadContext


CREATESTRUCT

typedef struct tagCREATESTRUCT { // cs

    LPVOID    lpCreateParams;

    HINSTANCE hInstance;

    HMENU     hMenu;

    HWND      hwndParent;

    int       cy;

    int       cx;

    int       y;

    int       x;

    LONG      style;

    LPCTSTR   lpszName;

    LPCTSTR   lpszClass;

    DWORD     dwExStyle;

} CREATESTRUCT;

The CREATESTRUCT structure defines the initialization parameters passed to the window procedure of an application.

Members

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


CSADDR_INFO

typedef struct _CSADDR_INFO {

    SOCKET_ADDRESS  LocalAddr;

    SOCKET_ADDRESS  RemoteAddr;

    INT             iSocketType;

    INT             iProtocol;

} CSADDR_INFO;

The CSADDR_INFO structure contains Windows Sockets address information for a network service or name space provider. The GetAddressByName function obtains Windows Sockets address information using CSADDR_INFO structures.

LocalAddr

Specifies a Windows Sockets local address.

In a client application, pass this address to the bind function to obtain access to a network service.

In a network service, pass this address to the bind function so that the service is bound to the appropriate local address.

RemoteAddr

Specifies a Windows Sockets remote address. There are several uses for this remote address:

•	You can use this remote address to connect to the service via the connect function. This is useful if an application performs send/receive operations that involve connection-oriented protocols.

•	You can use this remote address with the sendto function when you are communicating over a connectionless (datagram) protocol. If you are using a connectionless protocol, such as UDP, sendto is typically the way you pass data to the remote system.

iSocketType

Specifies the type of the Windows socket. The following socket types are defined in WINSOCK.H:

Value	Socket Type
SOCK_STREAM	Stream.This is a protocol that sends data as a stream of bytes, with no message boundaries.
SOCK_DGRAM	Datagram. This is a connectionless protocol. There is no virtual circuit setup. There are typically no reliability guarantees. Services use recvfrom to obtain datagrams. The listen and accept functions do not work with datagrams.
SOCK_RDM	Reliably-Delivered Message. This is a protocol that preserves message boundaries in data.
SOCK_SEQPACKET	Sequenced packet stream. This is a protocol that is essentially the same as SOCK_RDM.
iProtocol

Specifies a value to pass as the protocol parameter to the socket function to open a socket for this service.

See Also

bind, connect, GetAddressByName, recv, send, sendto


CURRENCYFMT

typedef struct _currencyfmt {

    UINT      NumDigits;

    UINT      LeadingZero;

    UINT      Grouping;

    LPTSTR    lpDecimalSep;

    LPTSTR    lpThousandSep;

    UINT      NegativeOrder;

    UINT      PositiveOrder;

    LPTSTR    lpCurrencySymbol;
} CURRENCYFMT;

The CURRENCYFMT structure contains information that defines the format of a currency string. The GetCurrencyFormat function uses this information to customize a currency string for a specified locale.

Members

NumDigits

Specifies the number of fractional digits. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_IDIGITS.

LeadingZero

Specifies whether to use leading zeroes in decimal fields. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ILZERO.

Grouping

Specifies the size of each group of digits to the left of the decimal. Values in the range 0 − 9 are valid.

lpDecimalSep

Points to a null-terminated decimal separator string.

lpThousandSep

Points to a null-terminated thousand separator string.

NegativeOrder

Specifies the negative currency mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_INEGCURR.

PositiveOrder

Specifies the positive currency mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ICURRENCY.

lpCurrencySymbol

Points to a null-terminated currency symbol string.

See Also

GetCurrencyFormat


CURSORSHAPE

typedef struct tagCURSORSHAPE {    // cs

    int     xHotSpot;

    int     yHotSpot;

    int     cx;

    int     cy;

    int     cbWidth;

    BYTE    Planes;

    BYTE    BitsPixel;

} CURSORSHAPE, FAR *LPCURSORSHAPE;

The CURSORSHAPE structure contains information about a cursor.

Members

xHotSpot

Specifies the horizontal position of the hot spot, relative to the upper left corner of the cursor bitmap.

yHotSpot

Specifies the vertical position of the hot spot, relative to the upper left corner of the cursor bitmap.

cx

Specifies the width, in pixels, of the cursor.

cy

Specifies the height, in pixels, of the cursor.

cbWidth

Width, in bytes, of the cursor bitmap.

Planes

Specifies the number of color planes.

BitsPixel

Specifies the number of bits used to indicate the color of a single pixel in the cursor.

Remarks

When an application passes a cursor handle to the LockResource function, the function returns a pointer to a buffer containing information about the cursor. An application can use the CURSORSHAPE structure to access the information.

See Also

LockResource


CWPRETSTRUCT  (preliminaryWindows 95)
CWPRETSTRUCT  [image]  (preliminary−Windows 95)

typedef struct tagCWPRETSTRUCT { // cwprs

    LRESULT lResult;

    LPARAM  lParam;

    WPARAM  wParam;

    DWORD   message;

    HWND    hwnd;

} CWPRETSTRUCT;

The CWPRETSTRUCT structure defines the message parameters passed to a WH_CALLWNDPROCRET hook procedure.

Members

lResult

Specifies the return value of the window procedure that processed the message specified by the message value.

lParam

Specifies additional information about the message. The exact meaning depends on the message value.

wParam

Specifies additional information about the message. The exact meaning depends on the message value.

message

Specifies the message.

hwnd

Identifies the window that processed the message specified by the message value.

See Also

CallWndRetProc, SetWindowsHook, SetWindowsHookEx


CWPSTRUCT

typedef struct tagCWPSTRUCT { // cwps

    LPARAM  lParam;

    WPARAM  wParam;

    UINT    message;

    HWND    hwnd;

} CWPSTRUCT;

The CWPSTRUCT structure defines the message parameters passed to a WH_CALLWNDPROC hook procedure.

Members

lParam

Specifies additional information about the message. The exact meaning depends on the message value.

wParam

Specifies additional information about the message. The exact meaning depends on the message value.

message

Specifies the message.

hwnd

Identifies the window to receive the message.

See Also

CallWndProc, SetWindowsHook, SetWindowsHookEx


DATATYPES_INFO_1

typedef struct _DATATYPES_INFO_1 {

    LPTSTR pName;

} DATATYPES_INFO_1;

The DATATYPES_INFO_1 structure contains information about the data type used to record a print job.

Members

pName

Points to a null-terminated string that identifies the data type used to record a print job.

See Also

EnumPrintProcessorDataTypes


DCB

typedef struct _DCB { // dcb

    DWORD DCBlength;           // sizeof(DCB)

    DWORD BaudRate;            // current baud rate

    DWORD fBinary: 1;          // binary mode, no EOF check

    DWORD fParity: 1;          // enable parity checking

    DWORD fOutxCtsFlow:1;      // CTS output flow control

    DWORD fOutxDsrFlow:1;      // DSR output flow control

    DWORD fDtrControl:2;       // DTR flow control type

    DWORD fDsrSensitivity:1;   // DSR sensitivity

    DWORD fTXContinueOnXoff:1; // XOFF continues Tx

    DWORD fOutX: 1;        // XON/XOFF out flow control

    DWORD fInX: 1;         // XON/XOFF in flow control

    DWORD fErrorChar: 1;   // enable error replacement

    DWORD fNull: 1;        // enable null stripping

    DWORD fRtsControl:2;   // RTS flow control

    DWORD fAbortOnError:1; // abort reads/writes on error

    DWORD fDummy2:17;      // reserved

    WORD wReserved;        // not currently used

    WORD XonLim;           // transmit XON threshold

    WORD XoffLim;          // transmit XOFF threshold

    BYTE ByteSize;         // number of bits/byte, 4-8

    BYTE Parity;           // 0-4=no,odd,even,mark,space

    BYTE StopBits;         // 0,1,2 = 1, 1.5, 2

    char XonChar;          // Tx and Rx XON character

    char XoffChar;         // Tx and Rx XOFF character

    char ErrorChar;        // error replacement character

    char EofChar;          // end of input character

    char EvtChar;          // received event character

    WORD wReserved1;       // reserved; do not use

} DCB;

The DCB structure defines the control setting for a serial communications device.

Members

DCBlength

Specifies the length, in bytes, of the DCB structure.

BaudRate

Specifies the baud rate at which the communications device operates. This member can be an actual baud rate value, or one of the following baud rate indexes:

CBR_110	CBR_19200
CBR_300	CBR_38400
CBR_600	CBR_56000
CBR_1200	CBR_57600
CBR_2400	CBR_115200
CBR_4800	CBR_128000
CBR_9600	CBR_256000
CBR_14400
fBinary

Specifies whether binary mode is enabled. The Win32 API does not support nonbinary mode transfers, so this member should be TRUE. Trying to use FALSE will not work.

Under Windows 3.1, if this member is FALSE, nonbinary mode is enabled, and the character specified by the EofChar member is recognized on input and remembered as the end of data.

fParity

Specifies whether parity checking is enabled. If this member is TRUE, parity checking is performed and errors are reported.

fOutxCtsFlow

Specifies whether the CTS (clear-to-send) signal is monitored for output flow control. If this member is TRUE and CTS is turned off, output is suspended until CTS is sent again.

fOutxDsrFlow

Specifies whether the DSR (data-set-ready) signal is monitored for output flow control. If this member is TRUE and DSR is turned off, output is suspended until DSR is sent again.

fDtrControl

Specifies the DTR (data-terminal-ready) flow control. This member can be one of the following values:

Value	Meaning
DTR_CONTROL_DISABLE	Disables the DTR line when the device is opened and leaves it disabled.
DTR_CONTROL_ENABLE	Enables the DTR line when the device is opened and leaves it on.
DTR_CONTROL_HANDSHAKE	Enables DTR handshaking. If handshaking is enabled, it is an error for the application to adjust the line by using the EscapeCommFunction function.
fDsrSensitivity

Specifies whether the communications driver is sensitive to the state of the DSR signal. If this member is TRUE, the driver ignores any bytes received, unless the DSR modem input line is high.

fTXContinueOnXoff

Specifies whether transmission stops when the input buffer is full and the driver has transmitted the XoffChar character. If this member is TRUE, transmission continues after the input buffer has come within XoffLim bytes of being full and the driver has transmitted the XoffChar character to stop receiving bytes. If this member is FALSE, transmission does not continue until the input buffer is within XonLim bytes of being empty and the driver has transmitted the XonChar character to resume reception.

fOutX

Specifies whether XON/XOFF flow control is used during transmission. If this member is TRUE, transmission stops when the XoffChar character is received and starts again when the XonChar character is received.

fInX

Specifies whether XON/XOFF flow control is used during reception. If this member is TRUE, the XoffChar character is sent when the input buffer comes within XoffLim bytes of being full, and the XonChar character is sent when the input buffer comes within XonLim bytes of being empty.

fErrorChar

Specifies whether bytes received with parity errors are replaced with the character specified by the ErrorChar member. If this member is TRUE and the fParity member is TRUE, replacement occurs.

fNull

Specifies whether null bytes are discarded. If this member is TRUE, null bytes are discarded when received.

fRtsControl

Specifies the RTS (request-to-send) flow control. If this value is zero, the default is RTS_CONTROL_HANDSHAKE. This member can be one of the following values:

Value	Meaning
RTS_CONTROL_DISABLE	Disables the RTS line when the device is opened and leaves it disabled.
RTS_CONTROL_ENABLE	Enables the RTS line when the device is opened and leaves it on.
RTS_CONTROL_HANDSHAKE	Enables RTS handshaking. The driver raises the RTS line when the "type-ahead" (input) buffer is less than one-half full and lowers the RTS line when the buffer is more than three-quarters full. If handshaking is enabled, it is an error for the application to adjust the line by using the EscapeCommFunction function.
RTS_CONTROL_TOGGLE	Specifies that the RTS line will be high if bytes are available for transmission. After all buffered bytes have been sent, the RTS line will be low.
fAbortOnError

Specifies whether read and write operations are terminated if an error occurs. If this member is TRUE, the driver terminates all read and write operations with an error status if an error occurs. The driver will not accept any further communications operations until the application has acknowledged the error by calling the ClearCommError function.

fDummy2

Reserved; do not use.

wReserved

Not used; must be set to zero.

XonLim

Specifies the minimum number of bytes allowed in the input buffer before the XON character is sent.

XoffLim

Specifies the maximum number of bytes allowed in the input buffer before the XOFF character is sent. The maximum number of bytes allowed is calculated by subtracting this value from the size, in bytes, of the input buffer.

ByteSize

Specifies the number of bits in the bytes transmitted and received.

Parity

Specifies the parity scheme to be used. This member can be one of the following values:

Value	Meaning
EVENPARITY	Even
MARKPARITY	Mark
NOPARITY	No parity
ODDPARITY	Odd
StopBits

Specifies the number of stop bits to be used. This member can be one of the following values:

Value	Meaning
ONESTOPBIT	1 stop bit
ONE5STOPBITS	1.5 stop bits
TWOSTOPBITS	2 stop bits
XonChar

Specifies the value of the XON character for both transmission and reception.

XoffChar

Specifies the value of the XOFF character for both transmission and reception.

ErrorChar

Specifies the value of the character used to replace bytes received with a parity error.

EofChar

Specifies the value of the character used to signal the end of data.

EvtChar

Specifies the value of the character used to signal an event.

wReserved1

Reserved; do not use.

Remarks

When a DCB structure is used to configure the 8250, the following restrictions apply to the values specified for the ByteSize and StopBits members:

•	The number of data bits must be 5 to 8 bits.

•	The use of 5 data bits with 2 stop bits is an invalid combination, as is 6, 7, or 8 data bits with 1.5 stop bits.

See Also

BuildCommDCB, ClearCommError, EscapeCommFunction, GetCommState, SetCommState


DDEACK

typedef struct { // ddeack

    unsigned short bAppReturnCode:8,

    reserved:6,

    fBusy:1,

    fAck:1;

} DDEACK;

The DDEACK structure contains status flags that a DDE application passes to its partner as part of the WM_DDE_ACK message. The flags provide details about the application's response to the messages WM_DDE_DATA, WM_DDE_POKE, WM_DDE_EXECUTE, WM_DDE_ADVISE, WM_DDE_UNADVISE, and WM_DDE_REQUEST.

Members

bAppReturnCode

Specifies an application-defined return code.

fBusy

Indicates whether the application was busy and unable to respond to the partner's message at the time the message was received. A nonzero value indicates the partner was busy and unable to respond. The fBusy member is defined only when the fAck member is zero.

fAck

Indicates whether the application accepted the message from its partner. A nonzero value indicates the partner accepted the message.

See Also

WM_DDE_ACK, WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_EXECUTE, WM_DDE_REQUEST, WM_DDE_POKE, WM_DDE_UNADVISE


DDEADVISE

typedef struct { // ddeadv

    unsigned short reserved:14,

        fDeferUpd:1,

        fAckReq:1;

    short cfFormat;

} DDEADVISE;

The DDEADVISE structure contains flags that specify how a DDE server application should send data to a client application during an advise loop. A client passes the handle of a DDEADVISE structure to a server as part of a WM_DDE_ADVISE message. This structure supersedes the DDELN structure.

Members

fDeferUpd

Indicates whether the server should defer sending updated data to the client. If this value is nonzero, the server should send a WM_DDE_DATA message with a NULL data handle whenever the data item changes. In response, the client can post a WM_DDE_REQUEST message to the server to get a handle of the updated data.

fAckReq

Indicates whether the server should set the fAckReq flag in the WM_DDE_DATA messages it posts to the client. If this value is nonzero, the server should set the fAckReq bit.

cfFormat

Specifies the client application's preferred data format. The format must be a standard or registered clipboard format. The following standard clipboard formats can be used:

CF_BITMAP
CF_DIB
CF_DIF
CF_ENHMETAFILE
CF_METAFILEPICT
CF_OEMTEXT
CF_PALETTE
CF_PENDATA
CF_RIFF
CF_SYLK
CF_TEXT
CF_TIFF
CF_WAVE
CF_UNICODETEXT

See Also

WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_UNADVISE


DDEDATA

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. This structure supersedes the DDEUP structure.

Members

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

Contains the data. The length and type of data depend on the cfFormat member.

See Also

DDEUP, WM_DDE_ACK, WM_DDE_ADVISE, WM_DDE_DATA, WM_DDE_POKE, WM_DDE_REQUEST


DDELN

typedef struct { // ddeln

    unsigned short unused:13,

        fRelease:1,

        fDeferUpd:1,

        fAckReq:1;

    short cfFormat;

} DDELN;

The DDELN structure is obsolete. Win32-based applications should use the DDEADVISE structure.

See Also

DDEADVISE, WM_DDE_ADVISE, WM_DDE_UNADVISE


DDEML_MSG_HOOK_DATA

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 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.

Members

uiLo

Specifies the unpacked low-order word of the lParam parameter associated with the DDE message.

uiHi

Specifies the unpacked high-order word of the lParam parameter associated with the DDE message.

cbData

Specifies the amount, in bytes, of data being passed with the message. This value can be greater than 32.

Data

Contains the first 32 bytes of data being passed with the message
(8 * sizeof(DWORD)).

See Also

MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


DDEPOKE

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. This structure supersedes the DDEUP structure.

Members

fRelease

Indicates whether the application receiving the WM_DDE_POKE message should free the data. If this value is nonzero, the application should free the data.

fReserved

Reserved; do not use.

cfFormat

Specifies the format of the data. The format should be a standard or registered clipboard format. The following standard clipboard formats can be used:

CF_BITMAP
CF_DIB
CF_DIF
CF_ENHMETAFILE
CF_METAFILEPICT
CF_OEMTEXT
CF_PALETTE
CF_PENDATA
CF_RIFF
CF_SYLK
CF_TEXT
CF_TIFF
CF_WAVE
CF_UNICODETEXT

Value

Contains the data. The length and type of data depend on the value of the cfFormat member.

See Also

DDEUP, WM_DDE_POKE


DDEUP

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-based applications should use the DDEDATA and DDEPOKE structures.

See Also

WM_DDE_DATA, WM_DDE_POKE


DEBUG_EVENT

typedef struct _DEBUG_EVENT { // de

    DWORD dwDebugEventCode;

    DWORD dwProcessId;

    DWORD dwThreadId;

    union {

        EXCEPTION_DEBUG_INFO Exception;

        CREATE_THREAD_DEBUG_INFO CreateThread;

        CREATE_PROCESS_DEBUG_INFO CreateProcessInfo;

        EXIT_THREAD_DEBUG_INFO ExitThread;

        EXIT_PROCESS_DEBUG_INFO ExitProcess;

        LOAD_DLL_DEBUG_INFO LoadDll;

        UNLOAD_DLL_DEBUG_INFO UnloadDll;

        OUTPUT_DEBUG_STRING_INFO DebugString;

        RIP_INFO RipInfo;

    } u;

} DEBUG_EVENT;

The DEBUG_EVENT structure describes a debugging event.

Members

dwDebugEventCode

Specifies a debugging event code that identifies the type of debugging event. This parameter can be one of the following values:

Value	Meaning
EXCEPTION_DEBUG_EVENT
	Reports an exception debugging event. The value of u.Exception specifies an EXCEPTION_DEBUG_INFO structure.
CREATE_THREAD_DEBUG_EVENT
	Reports a create-thread debugging event. The value of u.CreateThread specifies a CREATE_THREAD_DEBUG_INFO str structure.
CREATE_PROCESS_DEBUG_EVENT
	Reports a create-process debugging event. The value of u.CreateProcessInfo specifies a CREATE_PROCESS_DEBUG_INFO str structure.
EXIT_THREAD_DEBUG_EVENT
	Reports an exit-thread debugging event. The value of u.ExitThread specifies an EXIT_THREAD_DEBUG_INFO str structure.
EXIT_PROCESS_DEBUG_EVENT
	Reports an exit-process debugging event. The value of u.ExitProcess specifies an EXIT_PROCESS_DEBUG_INFO str structure.
LOAD_DLL_DEBUG_EVENT
	Reports a load-dynamic-link-library (DLL) debugging event. The value of u.LoadDll specifies a LOAD_DLL_DEBUG_INFO str structure.
UNLOAD_DLL_DEBUG_EVENT
	Reports an unload-DLL debugging event. The value of u.UnloadDll specifies an UNLOAD_DLL_DEBUG_INFO str structure.
OUTPUT_DEBUG_STRING_EVENT
	Reports an output-debugging-string debugging event. The value of u.DebugString specifies an OUTPUT_DEBUG_STRING_INFO str structure.
RIP_EVENT
	Reports a RIP-debugging event (system debugging error). The value of u.RipInfo specifies a RIP_INFO structure.
dwProcessId

Specifies the identifier of the process in which the debugging event occurred. A debugger uses this value to locate the debugger's per-process structure. These values are not necessarily small integers that can be used as table indices.

dwThreadId

Specifies the identifier of the thread in which the debugging event occurred. A debugger uses this value to locate the debugger's per-thread structure. These values are not necessarily small integers that can be used as table indices.

u

Specifies additional information relating to the debugging event. This union takes on the type and value appropriate to the type of debugging event, as described in the dwDebugEventCode member.

Remarks

If the WaitForDebugEvent function succeeds, it fills in the members of a DEBUG_EVENT structure.

See Also

CREATE_PROCESS_DEBUG_INFO, CREATE_THREAD_DEBUG_INFO, EXIT_PROCESS_DEBUG_INFO, EXIT_THREAD_DEBUG_INFO, EXCEPTION_DEBUG_INFO, LOAD_DLL_DEBUG_INFO, OUTPUT_DEBUG_STRING_INFO, UNLOAD_DLL_DEBUG_INFO, WaitForDebugEvent


DEBUGHOOKINFO

typedef struct tagDEBUGHOOKINFO { // dh

    DWORD  idThread;

    DWORD  idThreadInstaller;

    LPARAM lParam;

    WPARAM wParam;

    int    code;

} DEBUGHOOKINFO;

The DEBUGHOOKINFO structure contains debugging information.

Members

idThread

Identifies the thread containing the filter function.

idThreadInstaller

Identifies the thread that installed the debugging filter function.

lParam

Specifies the value to be passed to the hook in the lParam parameter of the DebugProc callback function.

wParam

Specifies the value to be passed to the hook in the wParam parameter of the DebugProc callback function.

code

Specifies the value to be passed to the hook in the nCode parameter of the DebugProc callback function.

See Also

DebugProc, SetWindowsHook, SetWindowsHookEx


DELETEITEMSTRUCT

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 with nonzero item data. The lParam parameter of the message contains a pointer to this structure.

Members

CtlType

Specifies ODT_LISTBOX (an owner-drawn list box) or ODT_COMBOBOX (an owner-drawn combo box).

CtlID

Specifies the identifier of the list box or combo box.

itemID

Specifies index of the item in the list box or combo box being removed.

hwndItem

Identifies the control.

itemData

Specifies application-defined data for the item. This value is passed to the control in the lParam parameter of the message that adds the item to the list box or combo box.

See Also

WM_DELETEITEM


DEV_BROADCAST_DEVNODE  (preliminaryWindows 95)
DEV_BROADCAST_DEVNODE  (preliminary−Windows 95)

typedef struct _DEV_BROADCAST_DEVNODE {
    ULONG dbcd_size;

    ULONG dbcd_devicetype;

    ULONG dbcd_reserved;

    ULONG dbcd_devnode;

} DEV_BROADCAST_DEVNODE;
typedef DEV_BROADCAST_DEVNODE *PDEV_BROADCAST_DEVNODE;

The DEV_BROADCAST_DEVNODE structure provides information about a device node.

Members

dbcd_size

Size of this structure, in bytes.

dbcd_devicetype

DBT_DEVTYP_DEVNODE.

dbcd_reserved

Reserved; do not use.

dbcd_devnode

Reserved; do not use.

Remarks

This structure is intended to be used to remove these defunct messages: DBT_DevAdd, DevStart, DevStop, DevRemove, DevQueryRemove, DevQueryRemoveFailed, DevQueryStop, and DevQueryStopFailed.


DEV_BROADCAST_HDR  (preliminaryWindows 95)
DEV_BROADCAST_HDR  (preliminary−Windows 95)

typedef struct _DEV_BROADCAST_HDR {
    ULONG dbch_size;

    ULONG dbch_devicetype;

    ULONG dbch_reserved;

} DEV_BROADCAST_HDR;
typedef DEV_BROADCAST_HDR *PDEV_BROADCAST_HDR;

The DEV_BROADCAST_HDR structure contains information about the device affected by a WM_DEVICECHANGE message.

Members

dbch_size

Size of this structure, in bytes.

dbch_devicetype

Type of device. Can be one of these values:

Value	Meaning
DBT_DEVTYP_OEM	OEM- or IHV-defined device type.
DBT_DEVTYP_DEVNODE	Reserved; do not use.
DBT_DEVTYP_VOLUME	Logical volume.
DBT_DEVTYP_PORT	Port device (serial or parallel).
DBT_DEVTYP_NET	Network adapter.
dbch_reserved

Reserved; do not use.

See Also

WM_DEVICECHANGE


DEV_BROADCAST_NET  (preliminaryWindows 95)
DEV_BROADCAST_NET  (preliminary−Windows 95)

typedef struct _DEV_BROADCAST_NET {
    ULONG dbcn_size;

    ULONG dbcn_devicetype;

    ULONG dbcn_reserved;

    ULONG dbcn_resource;

    ULONG dbcn_flags;

} DEV_BROADCAST_NET;
typedef DEV_BROADCAST_NET *PDEV_BROADCAST_NET;

The DEV_BROADCAST_NET structure contains information about a network connection or other resource.

Members

dbcn_size

Size of this structure, in bytes.

dbcn_devicetype

DBT_DEVTYP_NET.

dbcn_reserved

Reserved; do not use.

dbcn_resource

Handle to a network resource, typically a network connection.

dbcn_flags

Flags. Can be one of the following values:

Value	Meaning
DBTF_RESOURCE	Change affects network resource.
DBTF_XPORT	Change affects network transport; dbcn_resource not defined.
Remarks

A network redirector may send either DBT_DEVTYP_VOLUME or DBT_DEVTYP_NET. Other network services send DBT_DEVTYP_NET only. DBT_DEVTYP_NET messages provide more direct information about network connections for files and named pipes over UNC connections.


DEV_BROADCAST_OEM  (preliminaryWindows 95)
DEV_BROADCAST_OEM  (preliminary−Windows 95)

typedef struct _DEV_BROADCAST_OEM {
    ULONG dbco_size;

    ULONG dbco_devicetype;

    ULONG dbco_reserved;

    ULONG dbco_identifier;

    ULONG dbco_suppfunc;

} DEV_BROADCAST_OEM;
typedef DEV_BROADCAST_OEM *PDEV_BROADCAST_OEM;

The DEV_BROADCAST_OEM structure contains information about a OEM-defined device type.

Members

dbco_size

Size of this structure, in bytes.

dbco_devicetype

DBT_DEVTYPE_OEM.

dbco_reserved

Reserved; do not use.

dbco_identifier

Globally unique identifier (GUID) for the device. Use the uuidgen utility to create this identifier.

dbco_suppfunc

OEM-specific function value. Possible values depend on the device.


DEV_BROADCAST_PORT  (preliminaryWindows 95)
DEV_BROADCAST_PORT  (preliminary−Windows 95)

typedef struct _DEV_BROADCAST_PORT {
    ULONG dbcp_size;

    ULONG dbcp_devicetype;

    ULONG dbcp_reserved;

    char dbcp_name[1];

} DEV_BROADCAST_PORT;
typedef DEV_BROADCAST_PORT *PDEV_BROADCAST_PORT;

The DEV_BROADCAST_PORT structure contains information about a modem, serial, or parallel port.

Members

dbcp_size

Size of this structure, in bytes.

dbcp_devicetype

DBT_DEVTYP_VOLUME.

dbcp_reserved

Reserved; do not use.

dbcp_name

Null-terminated string specifying the friendly name of the port or the device connected to the port. Friendly names are intended to help the user quickly and accurately identify the device—for example, "COM1", "Hayes 2400 Smartmodem", and "LPT1" are considered friendly names.


_DEV_BROADCAST_USERDEFINED

struct _DEV_BROADCAST_USERDEFINED {
    struct _DEV_BROADCAST_HDR dbud_dbh;
    char  dbud_szName[1];           // ASCIIZ name
//    BYTE  dbud_rgbUserDefined[];  // Optional user-defined contents
};

The _DEV_BROADCAST_USERDEFINED structure contains the user-defined message and optional data associated with the DBT_USERDEFINED device message.

Members

dbud_dbh

Information about the device affected by a WM_DEVICECHANGE message as specified by the DEV_BROADCAST_HDR structure. Because the _DEV_BROADCAST_USERDEFINED structure is variable length, dbud_dbh.dbch_size must be the size in bytes of the entire structure, including the variable length part.

dbud_szName

A case-sensitive, null-terminated string that names the message. The name must consist of the vendor name, a backslash, followed by arbitrary user-defined null-terminated text. For example:

"WidgetWare\QueryScannerShutdown"

or

"WidgetWare\Video Q39S\AdapterReady"

dbud_rgbUserDefined

Optional user-defined information.

Because this structure contains variable length fields, use this structure tag as a template for creating a pointer to a user-defined structure. Note that the structure must not contain pointers. For example:

#define NAME_LENGTH 32

#define USER_LENGTH 50

typedef struct tagWIDGET_WARE_DEV_BROADCAST_USERDEFINED
{
    struct _DEV_BROADCAST_HDR DBHeader;
    char  szName[NAME_LENGTH]
    BYTE  UserDefined[USER_LENGTH];

} WIDGET_WARE_DEV_BROADCAST_USERDEFINED;

See Also

DBT_USERDEFINED, DEV_BROADCAST_HDR, WM_DEVICECHANGE


DEV_BROADCAST_VOLUME  (preliminaryWindows 95)
DEV_BROADCAST_VOLUME  (preliminary−Windows 95)

typedef struct _DEV_BROADCAST_VOLUME {
    ULONG dbcv_size;

    ULONG dbcv_devicetype;

    ULONG dbcv_reserved;

    ULONG dbcv_unitmask;

    USHORT dbcv_flags;

} DEV_BROADCAST_VOLUME;
typedef DEV_BROADCAST_VOLUME *PDEV_BROADCAST_VOLUME;

The DEV_BROADCAST_VOLUME structure contains information about a logical volume.

Members

dbcv_size

Size of this structure, in bytes.

dbcv_devicetype

DBT_DEVTYP_VOLUME.

dbcv_reserved

Reserved; do not use.

dbcv_unitmask

Logical unit mask identifying one or more logical units. Each bit in the mask corresponds to one logical drive. Bit 0 represents drive A, bit 1 drive B, and so on.

dbcv_flags

Flags indicating whether drive or media.

Value	Meaning
DBTF_MEDIA	Change affects media in drive. If not set, change affects physical device or drive.
DBTF_NET	Indicated logical volume is a network volume.
Remarks

Although the dbcv_unitmask member may specify more than one volume in any given message, this does not guarantee that only message is generated for a given event. Multiple system components may independently generate messages for logical volumes at the same time.


DEVMODE

typedef struct _devicemode {    // dvmd

    BCHAR  dmDeviceName[CCHDEVICENAME];

    WORD   dmSpecVersion;

    WORD   dmDriverVersion;

    WORD   dmSize;

    WORD   dmDriverExtra;

    DWORD  dmFields;

    short  dmOrientation;

    short  dmPaperSize;

    short  dmPaperLength;

    short  dmPaperWidth;

    short  dmScale;

    short  dmCopies;

    short  dmDefaultSource;

    short  dmPrintQuality;

    short  dmColor;

    short  dmDuplex;

    short  dmYResolution;

    short  dmTTOption;

    short  dmCollate;

    BCHAR  dmFormName[CCHFORMNAME];

    WORD  dmLogPixels;

    DWORD  dmBitsPerPel;

    DWORD  dmPelsWidth;

    DWORD  dmPelsHeight;

    DWORD  dmDisplayFlags;

    DWORD  dmDisplayFrequency;

#if(WINVER >= 0x0400)

    DWORD  dmICMMethod;         // Windows 95 only

    DWORD  dmICMIntent;         // Windows 95 only

    DWORD  dmMediaType;         // Windows 95 only

    DWORD  dmDitherType;        // Windows 95 only

    DWORD  dmICCManufacturer;   // Windows 95 only

    DWORD  dmICCModel;          // Windows 95 only

#endif /* WINVER >= 0x0400 */

} DEVMODE;

The DEVMODE data structure contains information about the device initialization and environment of a printer.

Members

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

A set of bit flags that specify whether certain members of the DEVMODE structure have been initialized. If a field is initialized, its corresponding bit flag is set, otherwise the bit flag is clear.  A printer driver supports only those DEVMODE structure members that are appropriate for the printer technology.

The following bit flags are defined, and are listed here with the corresponding structure members:

Value	Structure Member
DM_ORIENTATION	dmOrientation
DM_PAPERSIZE	dmPaperSize
DM_PAPERLENGTH	dmPaperLength
DM_PAPERWIDTH	dmPaperWidth
DM_SCALE	dmScale
DM_COPIES	dmCopies
DM_DEFAULTSOURCE	dmDefaultSource
DM_PRINTQUALITY	dmPrintQuality
DM_COLOR	dmColor
DM_DUPLEX	dmDuplex
DM_YRESOLUTION	dmYResolution
DM_TTOPTION	dmTTOption
DM_COLLATE	dmCollate
DM_FORMNAME	dmFormName
DM_LOGPIXELS	dmLogPixels
DM_BITSPERPEL	dmBitsPerPel
DM_PELSWIDTH	dmPelsWidth
DM_PELSHEIGHT	dmPelsHeight
DM_DISPLAYFLAGS	dmDisplayFlags
DM_DISPLAYFREQUENCY	dmDisplayFrequency
DM_ICMMETHOD	Windows 95 only: dmICMMethod
DM_ICMINTENT	Windows 95 only: dmICMIntent
DM_MEDIATYPE	Windows 95 only: dmMediaType
DM_DITHERTYPE	Windows 95 only: dmDitherType
DM_RESERVED1	Windows 95 only: dmICCManufacturer
DM_RESERVED2	Windows 95 only: dmICCModel
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	Collates when printing multiple copies.
DMCOLLATE_FALSE	Does 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 by using the EnumForms function.

dmLogPixels

Specifies the number of pixels per logical inch.

dmBitsPerPel

Specifies the color resolution, in bits per pixel, of the display device (for example: 4 bits for 16 colors, 8 bits for 256 colors, or 16 bits for 65536 colors).

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. This member can be one of the following values:

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.

dmICMMethod

Windows 95

Specifies how ICM is handled. For a non-ICM application, this member determines if ICM is enabled or disabled. For ICM applications, Windows examines this member to determine how to handle ICM support. This member can be one of the following predefined values, or a driver-defined value greater than the value of DMICMMETHOD_USER:

Value	Meaning
DMICMMETHOD_NONE	Windows 95 only: Specifies that ICM is disabled.
DMICMMETHOD_SYSTEM	Windows 95 only: Specifies that ICM is handled by Windows.
DMICMMETHOD_DRIVER	Windows 95 only: Specifies that ICM is handled by the device driver.
DMICMMETHOD_DEVICE	Windows 95 only: Specifies that ICM is handled by the destination device.
The printer driver must provide a user interface for setting this member. Most printer drivers support only the DMICMMETHOD_SYSTEM or DMICMMETHOD_NONE value. Drivers for PostScript printers support all values.

Windows NT

This member is not supported on Windows NT.

dmICMIntent

Windows 95

Specifies which of the three possible color matching methods, or intents, should be used by default. This member is primarily for non-ICM applications. ICM applications can establish intents by using the ICM functions. This member can be one of the following predefined values, or a driver defined value greater than the value of DMICM_USER:

Value	Meaning
DMICM_SATURATE	Windows 95 only: Color matching should optimize for color saturation. This value is the most appropriate choice for business graphs when dithering is not desired.
DMICM_CONTRAST	Windows 95 only: Color matching should optimize for color contrast. This value is the most appropriate choice for scanned or photographic images when dithering is desired.
DMICM_COLORMETRIC	Windows 95 only: Color matching should optimize to match the exact color requested. This value is most appropriate for use with business logos or other images when an exact color match is desired.
Windows NT

This member is not supported on Windows NT.

dmMediaType

Windows 95

Specifies the type of media being printed on. The member can be one of the following predefined values, or a driver-defined value greater than the value of DMMEDIA_USER:

Value	Meaning
DMMEDIA_STANDARD	Windows 95 only: Plain paper.
DMMEDIA_GLOSSY	Windows 95 only: Glossy paper.
DMMEDIA_TRANSPARENCY	Windows 95 only: Transparent film.
Windows NT

This member is not supported on Windows NT.

dmDitherType

Windows 95

Specifies how dithering is to be done. The member can be one of the following predefined values, or a driver-defined value greater than the value of DMDITHER_USER:

Value	Meaning
DMDITHER_NONE	Windows 95 only: No dithering.
DMDITHER_COARSE	Windows 95 only: Dithering with a coarse brush.
DMDITHER_FINE	Windows 95 only: Dithering with a fine brush.
DMDITHER_LINEART	Windows 95 only: Line art dithering, a special dithering method that produces well defined borders between black, white, and gray scalings. It is not suitable for images that include continuous graduations in intensisty and hue such as scanned photographs.
DMDITHER_GRAYSCALE	Windows 95 only: Device does grayscaling.
Windows NT

This member is not supported on Windows NT.

dmICCManufacturer

Windows 95

Not used; must be zero.

Windows NT

This member is not supported on Windows NT.

dmICCModel

Windows 95

Not used; must be zero.

Windows NT

This member is not supported on Windows NT.

Remarks

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

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.

Members

wDriverOffset

(Input/Output) Specifies the offset in characters from the beginning of this structure to a null-terminated string that contains the filename (without the extension) of the device driver. On input, this string is used to determine the printer to display initially in the dialog box.

wDeviceOffset

(Input/Output) Specifies the offset in characters from the beginning of this structure to the null-terminated string (maximum of 32 bytes including the null) that contains the name of the device. This string must be identical to the dmDeviceName member of the DEVMODE structure.

wOutputOffset

(Input/Output) Specifies the offset in characters from the beginning of this structure to the null-terminated string that contains the device name for the physical output medium (output port).

wDefault

Specifies whether the strings contained in the DEVNAMES structure identify the default printer. This string is used to verify that the default printer has not changed since the last print operation. On input, if the DN_DEFAULTPRN flag is specified, 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 used if the default printer was selected. If a specific printer is selected, the flag is not used. All other flags in this member are reserved for internal use by the Print Dialog box procedure.

See Also

DEVMODE, PrintDlg


DIBSECTION

typedef struct tagDIBSECTION {

    BITMAP              dsBm;

    BITMAPINFOHEADER    dsBmih;

    DWORD               dsBitfields[3];

    HANDLE              dshSection;

    DWORD               dsOffset;

} DIBSECTION;

The DIBSECTION structure contains information about a device-independent bitmap created by calling the CreateDIBSection function. A DIBSECTION structure includes information about the bitmap's dimensions, color format, color masks, optional file mapping object, and optional bit values storage offset. An application can obtain a filled-in DIBSECTION structure for a given device-independent bitmap by calling the GetObject function.

Members

dsBm

A BITMAP data structure that contains information about the device-independent bitmap: its type, its dimensions, its color capacities, and a pointer to its bit values.

dsBmih

A BITMAPINFOHEADER data structure that contains information about the color format of the device-independent bitmap.

dsBitfields

Specifies three DWORD color masks for the device-independent bitmap. This field is only valid when the biBitCount member of the BITMAPINFOHEADER structure has a value greater than 8. Each color mask indicates the bits within a bit value doubleword that are used to encode one of the three color channels (red, green, and blue).

dshSection

Contains a handle to the file mapping object that the CreateDIBSection function used to create the device-independent bitmap. If CreateDIBSection was called with a NULL value for its hSection parameter, causing the operating system to allocate memory for the bitmap, the dshSection member will be NULL.

dsOffset

Specifies the offset to the bitmap's bit values within the file mapping object referenced by dshSection. If dshSection is NULL, the dsOffset value has no meaning.

See Also

BITMAP, BITMAPINFOHEADER, CreateDIBSection, GetDIBColorTable, GetObject


DISK_GEOMETRY

typedef struct _DISK_GEOMETRY {

   LARGE_INTEGER  Cylinders;

   MEDIA_TYPE  MediaType;

   DWORD  TracksPerCylinder;

   DWORD  SectorsPerTrack;

   DWORD  BytesPerSector;

} DISK_GEOMETRY ;

The DISK_GEOMETRY structure describes the geometry of disk devices and media.

Members

Cylinders

The number of cylinders.

MediaType

The type of media. See MEDIA_TYPE.

TracksPerCylinder

The number of tracks per cylinder.

SectorsPerTrack

The number of sectors per track.

BytesPerSector

The number of bytes per sector

Remarks

The DeviceIoControl function receives a DISK_GEOMETRY structure in response to an IOCTL_DISK_GET_DRIVE_GEOMETRY device input and output contol (IOCTL) operation. The DeviceIoControl function receives an array of DISK_GEOMETRY structures in response to an IOCTL_DISK_GET_MEDIA_TYPES device I/O operation.

See Also

DeviceIoControl, IOCTL_DISK_GET_DRIVE_GEOMETRY, IOCTL_DISK_GET_MEDIA_TYPES, MEDIA_TYPE


DISK_PERFORMANCE

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.

Members

BytesRead

Specifies the number of bytes read.

BytesWritten

Specifies the number of bytes written.

ReadTime

Specifies the time it took to complete the read.

WriteTime

Specifies the time it took to complete the write.

ReadCount

Specifies the number of read operations.

WriteCount

Specifies the number of write operations.

QueueDepth

Specifies the depth of the queue.

Remarks

The DeviceIoControl function receives a DISK_PERFORMANCE structure in response to an IOCTL_DISK_PERFORMANCE device I/O operation.

See Also

DeviceIoControl, IOCTL_DISK_PERFORMANCE


DLGITEMTEMPLATE

typedef struct { // dlit

    DWORD style;

    DWORD dwExtendedStyle;

    short x;

    short y;

    short cx;

    short 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.

Members

style

Specifies the style of the control. This member can be a combination of window style values (such as WS_BORDER) and one or more of the control style values (such as BS_PUSHBUTTON and ES_LEFT).

dwExtendedStyle

Specifies extended styles for a window. This member is not used to create controls in dialog boxes, but applications that use dialog box templates can use it to create other types of windows.

x

Specifies the x-coordinate, in dialog box units, of the upper-left corner of the control. This coordinate is always relative to the upper-left corner of the dialog box's client area.

y

Specifies the y-coordinate, in dialog box units, of the upper-left corner of the control. This coordinate is always relative to the upper-left corner of the dialog box's client area.

cx

Specifies the width, in dialog box units, of the control.

cy

Specifies the height, in dialog box units, of the control.

id

Specifies the control identifier.

Remarks

In a 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 box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, CreateWindowEx, DialogBoxIndirect, DialogBoxIndirectParam, MapDialogRect


DLGTEMPLATE

typedef struct { // dltt

    DWORD style;

    DWORD dwExtendedStyle;

    WORD  cdit;

    short x;

    short y;

    short cx;

    short 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.

Members

style

Specifies the style of the dialog box. This member can be a combination of window style values (such as WS_CAPTION and WS_SYSMENU) and one or more of the following dialog box style values:

Value	Meaning
DS_ABSALIGN	Indicates that the coordinates of the dialog box are screen coordinates. If this style is not specified, Windows assumes they are client coordinates.
DS_CENTER	Centers the dialog box in the working area; that is, the area not obscured by the tray.
DS_CENTERMOUSE	Centers the mouse cursor in the dialog box.
DS_FIXEDSYS	Use SYSTEM_FIXED_FONT instead of SYSTEM_FONT.
DS_LOCALEDIT	Applies to 16-bit applications only. This style directs edit controls in the dialog box to allocate memory from the application's data segment. Otherwise, edit controls allocate storage from a global memory object.
DS_MODALFRAME	Creates a dialog box with a modal dialog-box frame that can be combined with a title bar and System menu by specifying the WS_CAPTION and WS_SYSMENU styles.
DS_NOFAILCREATE	Creates the dialog even if errors occur — for example, if a child window cannot be created or if the system cannot create a special data segment for an edit control.
DS_NOIDLEMSG	Suppresses WM_ENTERIDLE messages that Windows would otherwise send to the owner of the dialog box while the dialog box is displayed.
DS_RECURSE	Dialog style for control-like dialogs.
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. In Windows NT, this flag causes the dialog box to have 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 box units, of the upper-left corner of the dialog box.

y

Specifies the y-coordinate, in dialog box units, of the upper-left corner of the dialog box.

cx

Specifies the width, in dialog box units, of the dialog box.

cy

Specifies the height, in dialog box units, of the dialog box.

Remarks

In a dialog box template, the DLGTEMPLATE structure is always immediately followed by three variable-length arrays that specify the menu, class, and title for the dialog box. When the DS_SETFONT style is given, these arrays are also followed by a 16-bit value specifying point size and another variable-length array specifying a typeface name. Each array consists of one or more 16-bit elements.

The menu 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 point size of the font to use for the text in the dialog box and its controls. The typeface array is a null-terminated Unicode string specifying the name of the typeface for the font. When these values are given, Windows creates a font having the given size and typeface (if possible) and sends a WM_SETFONT message to the dialog box procedure and the control window procedures as it creates the dialog box and controls.

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 box units. You can convert these values to screen units (pixels) by using the MapDialogRect function.

See Also

CreateDialogIndirect, CreateDialogIndirectParam, DialogBoxIndirect, DialogBoxIndirectParam, MapDialogRect


DOC_INFO_1

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.

Members

pDocName

Points to a null-terminated string that specifies the name of the document.

pOutputFile

Points to a null-terminated string that specifies the name of an output file.

pDatatype

Points to a null-terminated string that identifies the type of data used to record the document.

See Also

StartDocPrinter


DOC_INFO_2  (preliminaryWindows 95)
DOC_INFO_2  (preliminary−Windows 95)

typedef struct _DOC_INFO_2 { // dci2

    LPTSTR pDocName;

    LPTSTR pOutputFile;

    LPTSTR pDatatype;

    DWORD  dwMode;

    DWORD  JobId;

} DOC_INFO_2;

The DOC_INFO_2 structure describes a document that will be printed.

Members

pDocName

Points to a null-terminated string that specifies the name of the document.

pOutputFile

Points to a null-terminated string that specifies the name of an output file.

pDatatype

Points to a null-terminated string that identifies the type of data used to record the document.

dwMode

Informs the print spooler of the nature of the data to follow. If this value is zero, the print spooler treats the data sent by subsequent calls to WritePrinter as a normal print job (whether or not it is spooled depends on the printer property). If this value is DI_CHANNEL, only a communications channel is opened. In this case, the data passed into subsequent calls to WritePrinter is sent to the printer or subsequent calls to ReadPrinter retrieve data from the printer. This mode remains effective until EndDoc is called.

JobId

Reserved for internal use; should be zero.

See Also

EndDoc, ReadPrinter, StartDocPrinter, WritePrinter


DOCINFO

typedef struct {    // di

    int     cbSize;

    LPCTSTR lpszDocName;

    LPCTSTR lpszOutput;

    LPCTSTR lpszDatatype;   // Windows 95 only; ignored on Windows NT

    DWORD   fwType;         // Windows 95 only; ignored on Windows NT

} DOCINFO;

The DOCINFO structure contains the input and output filenames and other information used by the StartDoc function.

Members

cbSize

Specifies the size, in bytes, of the structure.

lpszDocName

Points to a null-terminated string that specifies the name of the document.

lpszOutput

Points to a null-terminated string that specifies the name of an output file. If this pointer is NULL, the output will be sent to the device identified by the device context handle that was passed to the StartDoc function.

lpszDatatype

Windows 95:

Points to a null-terminated string that specifies the type of data used to record the print job.

Windows NT:

This member is ignored.

fwType

Windows 95:

Specifies additional information about the print job. Can be zero or DI_APPBANDING if the application will use banding. For optimal performance during printing, banding applications should specify DI_APPBANDING.

Windows NT:

This member is ignored.

See Also

StartDoc


DRAGLISTINFO  (preliminaryWindows NT)
DRAGLISTINFO  (preliminary−Windows NT)

Typedef struct {

    UINT uNotification;

    HWND hWnd;

    POINT ptCursor;

} DRAGLISTINFO, FAR *LPDRAGLISTINFO;

The DRAGLISTINFO structure contains information about a drag event. The pointer to DRAGLISTINFO is passed as the lParam parameter of the drag list message.

Members

uNotification

Notification code that specifies the type of drag event. This member can be one of the following values:

Value	Meaning
DL_BEGINDRAG	The user has clicked the left mouse button on a list item.
DL_CANCELDRAG	The user has canceled the drag operation by clicking the right mouse button or pressing the esc key.
DL_DRAGGING	The user has moved the mouse while dragging an item.
DL_DROPPED	The user has released the left mouse button, completing a drag operation.
hWnd

Handle to drag list box.

ptCursor

POINT structure that contains the current x- and y-coordinates of the mouse cursor.

See also

DL_BEGINDRAG, DL_CANCELDRAG, DL_DRAGGING, DL_DROPPED, POINT


DRAWITEMSTRUCT

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.

Members

CtlType

Specifies the control type. This member can be one of the following values:

Value	Meaning
ODT_BUTTON	Owner-drawn button
ODT_COMBOBOX	Owner-drawn combo box
ODT_LISTBOX	Owner-drawn list box
ODT_LISTVIEW	List view control
ODT_MENU	Owner-drawn menu item
ODT_STATIC	Owner-drawn static control
ODT_TAB	Tab control
CtlID

Specifies the identifier of the combo box, list box, button, or static control. This member is not used for a menu item.

itemID

Specifies the menu item identifier for a menu item or the index of the item in a list box or combo box. For an empty list box or combo box, this member can be −1. This allows the application to draw only the focus rectangle at the coordinates specified by the rcItem member even though there are no items in the control. This indicates to the user whether the list box or combo box has the focus. How the bits are set in the itemAction member determines whether the rectangle is to be drawn as though the list box or combo box has the focus.

itemAction

Specifies the drawing action required. This member can be one or more of the following values:

Value	Meaning
ODA_DRAWENTIRE	The entire control needs to be drawn.
ODA_FOCUS	The control has lost or gained the keyboard focus. The itemState member should be checked to determine whether the control has the focus.
ODA_SELECT	The selection status has changed. The itemState member should be checked to determine the new selection state.
itemState

Specifies the visual state of the item after the current drawing action takes place. This member can be a combination of the following values:

Value	Meaning
ODS_CHECKED	The menu item is to be checked. This bit is used only in a menu.
ODS_COMBOBOXEDIT	The drawing takes place in the selection field (edit control) of an ownerdrawn combo box.
ODS_DEFAULT	The item is the default item.
ODS_DISABLED	The item is to be drawn as disabled.
ODS_FOCUS	The item has the keyboard focus.
ODS_GRAYED	The item is to be grayed. This bit is used only in a menu.
ODS_SELECTED	The menu item's status is selected.
hwndItem

Identifies the control for combo boxes, list boxes, buttons, and static controls. For menus, this member identifies the menu containing the item.

hDC

Identifies a device context; this device context must be used when performing drawing operations on the control.

rcItem

Specifies a rectangle that defines the boundaries of the control to be drawn. This rectangle is in the device context specified by the hDC member. Windows automatically clips anything the owner window draws in the device context for combo boxes, list boxes, and buttons, but does not clip menu items. When drawing menu items, the owner window must not draw outside the boundaries of the rectangle defined by the rcItem member.

itemData

Specifies the application-defined 32-bit value associated with the menu item. For a control, this parameter specifies the value last assigned to the list box or combo box by the LB_SETITEMDATA or CB_SETITEMDATA message. If the list box or combo box has the LBS_HASSTRINGS or CBS_HASSTRINGS style, this value is initially zero. Otherwise, this value is initially the value that was passed to the list box or combo box in the lParam parameter of one of the following messages:

CB_ADDSTRING
CB_INSERTSTRING
LB_ADDSTRING
LB_INSERTSTRING

If ctlType is ODT_BUTTON or ODT_STATIC, itemData is zero.

See Also

CB_ADDSTRING, CB_INSERTSTRING, CB_SETITEMDATA, LB_ADDSTRING, LB_INSERTSTRING, SETITEMDATA, WM_DRAWITEM


DRAWTEXTPARAMS  (preliminaryWindows 95)
DRAWTEXTPARAMS  (preliminary−Windows 95)

typedef struct {

    UINT cbSize;

    int  iTabLength;

    int  iLeftMargin;

    int  iRightMargin;

    UINT uiLengthDrawn;

} DRAWTEXTPARAMS, FAR *LPDRAWTEXTPARAMS;

The DRAWTEXTPARAMS structure contains extended formatting options for the DrawTextEx function.

Members

cbSize

Specifies the structure size, in bytes.

iTabLength

Specifies the size of each tab stop, in units equal to the average character width.

iLeftMargin

Specifies the left margin, in units equal to the average character width.

iRightMargin

Specifies the right margin, in units equal to the average character width.

uiLengthDrawn

Receives the number of characters processed by DrawTextEx, including white-space characters. The number can be the length of the string or the index of the first line that falls below the drawing area. Note that DrawTextEx always processes the entire string if the DT_NOCLIP formatting flag is specified.

See Also

DrawTextEx


DRIVE_LAYOUT_INFORMATION

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.

Members

PartitionCount

The number of partitions on the drive.

Signature

A drive signature value.

PartitionEntry

A variable-sized array of PARTITION_INFORMATION structures, one structure for each partition on the drive.

Remarks

The DeviceIoControl function receives a DRIVE_LAYOUT_INFORMATION structure in response to an IOCTL_DISK_GET_DRIVE_LAYOUT device I/O operation. The DeviceIoControl function  uses a DRIVE_LAYOUT_INFORMATION structure as input to an IOCTL_DISK_SET_DRIVE_LAYOUT device I/O operation.

See Also

DeviceIoControl, IOCTL_DISK_GET_DRIVE_LAYOUT, IOCTL_DISK_SET_DRIVE_LAYOUT, PARTITION_INFORMATION


DRIVER_INFO_1

typedef struct _DRIVER_INFO_1 { // dri1

    LPTSTR pName;

} DRIVER_INFO_1;

The DRIVER_INFO_1 structure identifies a printer driver.

Members

pName

Points to a null-terminated string that specifies the name of a printer driver.

See Also

EnumPrinterDrivers


DRIVER_INFO_2

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.

Members

cVersion

Specifies a printer-driver version number.

pName

Points to a null-terminated string that specifies the name of the driver (for example, "QMS 810").

pEnvironment

Points to a null-terminated string that specifies the environment for which the driver was written (for example, "Windows NT x86" or "Windows NT R4000").

pDriverPath

Points to null-terminated string that specifies a filename or full path and filename for the file that contains the device driver (for example, "c:\drivers\pscript.dll").

pDataFile

Points to a null-terminated string that specifies a filename or a full path and filename for the file that contains driver data (for example, "c:\drivers\QMS810.PPD").

pConfigFile

Points to a null-terminated string that specifies a filename or a full path and filename for the device-driver's configuration DLL (for example, "c:\drivers\PSCRPTUI.DLL").

See Also

AddPrinterDriver, GetPrinterDriver


DRIVER_INFO_3  (preliminaryWindows 95)
DRIVER_INFO_3  [image]  (preliminary−Windows 95)

typedef struct _DRIVER_INFO_3 { // dri3

    DWORD  cVersion;

    LPTSTR pName;

    LPTSTR pEnvironment;

    LPTSTR pDriverPath;

    LPTSTR pDataFile;

    LPTSTR pConfigFile;

    LPTSTR pHelpFile;

    LPTSTR pDependentFiles;

    LPTSTR pMonitorName;

    LPTSTR pDefaultDataType;

} DRIVER_INFO_3;

The DRIVER_INFO_3 structure contains printer driver information.

Members

cVersion

Specifies a printer-driver version number.

pName

Points to a null-terminated string that specifies the name of the driver (for example, "QMS 810").

pEnvironment

Points to a null-terminated string that specifies the environment for which the driver was written (for example, "Windows x86" or "Windows NT R4000").

pDriverPath

Points to a null-terminated string that specifies a filename or full path and filename for the file that contains the device driver (for example, "C:\DRIVERS\PSCRIPT.DLL").

pDataFile

Points to a null-terminated string that specifies a filename or a full path and filename for the file that contains driver data (for example, "C:\DRIVERS\QMS810.PPD").

pConfigFile

Points to a null-terminated string that specifies a filename or a full path and filename for the device driver's configuration dynamic-link library (for example, "C:\DRIVERS\PSCRPTUI.DLL").

pHelpFile

Points to a null-terminated string that specifies a filename or a full path and filename for the device driver's help file.

pDependentFiles

Points to a null-terminated string that specifies the files the driver is dependent on. Each filename in the string is also terminated with a null (for example, "PSCRIPT.DLL\0QMS810.PPD\0PSCRPTUI.DLL\0PSPCRIPTUI.HLP\0PSTEST.TXT\0\0").

pMonitorName

Points to a null-terminated string that specifies a language monitor (for example, "PJL monitor"). This member can be NULL and should be specified only for printers capable of bidirectional communication.

pDefaultDataType

Points to a null-terminated string that specifies the default data type of the print job (for example, "EMF").

See Also

AddPrinterDriver, EnumPrinterDrivers, GetPrinterDriver


EDITSTREAM  (preliminaryWindows NT)
EDITSTREAM  (preliminary−Windows NT)

typedef struct _editstream {

    DWORD dwCookie;

    DWORD dwError;

    EDITSTREAMCALLBACK pfnCallback;

} EDITSTREAM;

The EDITSTREAM structure contains information about a data stream used with a rich edit control.

Members

dwCookie

Application-defined value that is passed to the callback function.

dwError

Error encountered while streaming. If there was no error, this member is zero.

pfnCallback

Pointer to an application-defined function that the control calls to transfer data.

This structure is used with the EM_STREAMIN message to read (stream in) data into a rich edit control, replacing its contents. It is used with the EM_STREAMOUT message to write (stream out) the contents of a rich edit control.

The control calls the callback function repeatedly, transferring a portion of the data with each call. The callback function has the following form:

DWORD CALLBACK EditStreamCallback(DWORD dwCookie,

    LPBYTE pbBuff, LONG cb, LONG FAR *pcb);

dwCookie

Value of the dwCookie member of the EDITSTREAM structure.

pbBuff

Pointer to the buffer to read from or write to.

cb

Count of bytes to read or write.

pcb

Pointer to a variable that receives the number of bytes actually read or written.

Return Value

The return value depends on direction. If data is streaming in, the return value is the number of bytes copied to the buffer, or zero if the transfer is complete.

If data is streaming out, the return value is a nonzero value to continue to the transfer operation, or zero to abort it.

See Also

EM_STREAMIN, EM_STREAMOUT


EMR

typedef struct tagEMR
{
    DWORD iType;

    DWORD nSize;
} EMR, *PEMR;

The EMR structure provides the base structure for all enhanced metafile records. An enhanced metafile record contains the parameters for a specific GDI function used to create part of a picture in an enhanced format metafile.

Members

iType

Specifies the record type.

nSize

Size of the record, in bytes. This member must be a multiple of four.


EMRANGLEARC

typedef struct tagEMRANGLEARC
{
    EMR     emr;
    POINTL  ptlCenter;

    DWORD   nRadius;
    FLOAT   eStartAngle;
    FLOAT   eSweepAngle;
} EMRANGLEARC, *PEMRANGLEARC;

The EMRANGLEARC structure contains members for the AngleArc enhanced metafile record.

Members

emr

Base structure for all record types.

ptlCenter

Logical coordinates of circle's center.

nRadius

Circle's radius, in logical units.

eStartAngle

Arc's start angle, in degrees.

eSweepAngle

Arc's sweep angle, in degrees.

See Also

AngleArc


EMRARC, EMRARCTO, EMRCHORD, EMRPIE

typedef struct tagEMRARC
{
    EMR    emr;

    RECTL  rclBox;
    POINTL ptlStart;
    POINTL ptlEnd;
} EMRARC,   *PEMRARC,
  EMRARCTO, *PEMRARCTO,
  EMRCHORD, *PEMRCHORD,
  EMRPIE,   *PEMRPIE;

The EMRARC, EMRARCTO, EMRCHORD, and EMRPIE structures contain members for the Arc, ArcTo, Chord, and Pie enhanced metafile records.

Members

emr

Base structure for all record types.

rclBox

Bounding rectangle.

ptlStart

Coordinates of first radial ending point.

ptlEnd

Coordinates of second radial ending point.

See Also

Arc, ArcTo, Chord, Pie


EMRBITBLT

typedef struct tagEMRBITBLT
{
    EMR      emr;

    RECTL    rclBounds;

    LONG     xDest;

    LONG     yDest;

    LONG     cxDest;

    LONG     cyDest;

    DWORD    dwRop;

    LONG     xSrc;

    LONG     ySrc;

    XFORM    xformSrc;

    COLORREF crBkColorSrc;

    DWORD    iUsageSrc;

    DWORD    offBmiSrc;

    DWORD    offBitsSrc;

    DWORD    cbBitsSrc;

} EMRBITBLT, *PEMRBITBLT;

The EMRBITBLT structure contains members for the BitBlt enhanced metafile record. Note that graphics device interface (GDI) converts the device-dependent bitmap into a device-independent bitmap (DIB) before storing it in the metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

xDest

Logical x-coordinate of the upper-left corner of the destination rectangle.

yDest

Logical y-coordinate of the upper-left corner of the destination rectangle.

dwRop

Raster-operation code. These codes define how the color data of the source rectangle is to be combined with the color data of the destination rectangle to achieve the final color.

xSrc

Logical x-coordinate of the upper-left corner of the source rectangle.

ySrc

Logical y-coordinate of the upper-left corner of the source rectangle.

xformSrc

World-space to page-space transformation of the source device context.

crBkColorSrc

Background color (the RGB value) of the source device context.

iUsageSrc

Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES or DIB_RGB_COLORS value.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

See Also

BitBlt, BITMAPINFO, RGB


EMRCREATEBRUSHINDIRECT

typedef struct tagEMRCREATEBRUSHINDIRECT
{
    EMR      emr;

    DWORD    ihBrush;

    LOGBRUSH lb;

} EMRCREATEBRUSHINDIRECT, *PEMRCREATEBRUSHINDIRECT;

The EMRCREATEBRUSHINDIRECT structure contains members for the CreateBrushIndirect enhanced metafile record.

Members

emr

Base structure for all record types.

ihBrush

Index of brush in handle table.

lb

LOGBRUSH structure containing information about the brush. The lbStyle member must be either the BS_SOLID, BS_HOLLOW, BS_NULL, or BS_HATCHED value.

CreateBrushIndirect, LOGBRUSH


EMRCREATECOLORSPACE  (preliminaryWindows 95)
EMRCREATECOLORSPACE  (preliminary−Windows 95)

typedef struct tagEMRCREATECOLORSPACE
{
    EMR           emr;

    DWORD         ihCS;

    LOGCOLORSPACE lcs;

} EMRCREATECOLORSPACE, *PEMRCREATECOLORSPACE;

The EMRCREATECOLORSPACE structure contains members for the CreateColorSpace enhanced metafile record.

Members

emr

Base structure for all record types

ihCS

Index of the color cpace in handle table

lcs

Logical color space

See Also

CreateColorSpace


EMRCREATEDIBPATTERNBRUSHPT

typedef struct tagEMRCREATEDIBPATTERNBRUSHPT
{
    EMR   emr;

    DWORD ihBrush;

    DWORD iUsage;

    DWORD offBmi;

    DWORD cbBmi;

    DWORD offBits;

    DWORD cbBits;

} EMRCREATEDIBPATTERNBRUSHPT,
PEMRCREATEDIBPATTERNBRUSHPT;

The EMRCREATEDIBPATTERNBRUSHPT structure contains members for the CreateDIBPatternBrushPt enhanced metafile record. The BITMAPINFO structure is followed by the bitmap bits that form a packed device-independent bitmap (DIB).

Members

emr

Base structure for all record types.

ihBrush

Index of brush in handle table.

iUsage

Value specifying whether the bmiColors member of the BITMAPINFO structure was provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or indices. The iUsage member must be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

offBmi

Offset to BITMAPINFO structure.

cbBmi

Size of BITMAPINFO structure.

offBits

Offset to bitmap bits.

cbBits

Size of bitmap bits.

See Also

BITMAPINFO, CreateDIBPatternBrushPt, RGB


EMRCREATEMONOBRUSH

typedef struct tagEMRCREATEMONOBRUSH
{
    EMR   emr;

    DWORD ihBrush;

    DWORD iUsage;

    DWORD offBmi;

    DWORD cbBmi;

    DWORD offBits;

    DWORD cbBits;

} EMRCREATEMONOBRUSH, *PEMRCREATEMONOBRUSH;

The EMRCREATEMONOBRUSH structure contains members for the CreatePatternBrush (when passed a monochrome bitmap) or CreateDIBPatternBrush (when passed a monochrome DIB) enhanced metafile records.

Members

emr

Base structure for all record types.

ihBrush

Index of brush in handle table.

iUsage

Value specifying whether the bmiColors member of the BITMAPINFO structure was provided and, if so, whether bmiColors contains explicit red, green, blue (RGB) values or indices. The iUsage member must be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

offBmi

Offset to BITMAPINFO structure.

cbBmi

Size of BITMAPINFO structure.

offBits

Offset to bitmap bits.

cbBits

Size of bitmap bits.

See Also

BITMAPINFO, CreateDIBPatternBrush, CreatePatternBrush, RGB


EMRCREATEPALETTE

typedef struct tagEMRCREATEPALETTE
{
    EMR        emr;

    DWORD      ihPal;

    LOGPALETTE lgpl;

} EMRCREATEPALETTE, *PEMRCREATEPALETTE;

The EMRCREATEPALETTE structure contains members for the CreatePalette enhanced metafile record.

Members

emr

Base structure for all record types.

ihPal

Index of palette in handle table.

lgpl

LOGPALETTE structure that contains information about the palette. Note that peFlags members in the PALETTEENTRY structures do not contain any flags.

See Also

CreatePalette, LOGPALETTE, PALETTEENTRY


EMRCREATEPEN

typedef struct tagEMRCREATEPEN
{
    EMR    emr;

    DWORD  ihPen;

    LOGPEN lopn;

} EMRCREATEPEN, *PEMRCREATEPEN;

The EMRCREATEPEN structure contains members for the CreatePen enhanced metafile record.

Members

emr

Base structure for all record types

ihPen

Index to pen in handle table

lopn

Logical pen

See Also

CreatePen


EMRELLIPSE, EMRRECTANGLE

typedef struct tagEMRELLIPSE
{
    EMR   emr;

    RECTL rclBox;

} EMRELLIPSE,  *PEMRELLIPSE,
  EMRRECTANGLE, *PEMRRECTANGLE;

The EMRELLIPSE and EMRRECTANGLE structures contain members for the Ellipse and Rectangle enhanced metafile records.

Members

emr

Base structure for all record types.

rclBox

Bounding rectangle.

See Also

Ellipse, Rectangle


EMREOF

typedef struct tagEMREOF
{
    EMR     emr;
    DWORD   nPalEntries;

    DWORD   offPalEntries;

    DWORD   nSizeLast;

} EMREOF, *PEMREOF;

The EMREOF structure contains data for the enhanced metafile record that indicates the end of the metafile.

Members

emr

Base structure for all record types.

nPalEntries

Number of palette entries.

offPalEntires

Offset to palette entries.

nSizeLast

Same size as the nSize member of the EMR structure. This member must be the last doubleword of the record. If palette entries exist, they precede this member.

See Also

EMR


EMREXCLUDECLIPRECT, EMRINTERSECTCLIPRECT

typedef struct tagEMREXCLUDECLIPRECT
{
    EMR   emr;      // base structure for all record types
    RECTL rclClip;  // clipping rectangle
} EMREXCLUDECLIPRECT,   *PEMREXCLUDECLIPRECT,
  EMRINTERSECTCLIPRECT, *PEMRINTERSECTCLIPRECT;

The EMREXCLUDECLIPRECT and EMRINTERSECTCLIPRECTstructures contain members for the ExcludeClipRect and IntersectClipRect enhanced metafile records.

Members

emr

Base structure for all record types.

rclClip

Clipping rectangle.

ExcludeClipRect, IntersectClipRect


EMREXTCREATEFONTINDIRECTW

typedef struct tagEMREXTCREATEFONTINDIRECTW
{
    EMR         emr;

    DWORD       ihFont;

    EXTLOGFONTW elfw;

} EMREXTCREATEFONTINDIRECTW,
PEMREXTCREATEFONTINDIRECTW;

The EMREXTCREATEFONTINDIRECTW structure contains members for the CreateFontIndirect enhanced metafile record.

Members

emr

Base structure for all record types.

ihFont

Index to the font in handle table.

elfw

Logical font.

See Also

CreateFontIndirect


EMREXTCREATEPEN

typedef struct tagEMREXTCREATEPEN
{
    EMR       emr;

    DWORD     ihPen;

    DWORD     offBmi;

    DWORD     cbBmi;

    DWORD     offBits;

    DWORD     cbBits;

    EXTLOGPEN elp;

} EMREXTCREATEPEN, *PEMREXTCREATEPEN;

The EMREXTCREATEPEN structure contains members for the ExtCreatePen enhanced metafile record. If the record contains a BITMAPINFO structure, it is followed by the bitmap bits that form a packed device-independent bitmap (DIB).

Members

emr

Base structure for all record types.

ihPen

Index to pen in handle table.

offBmi

Offset to BITMAPINFO structure, if any.

cbBmi

Size of BITMAPINFO structure, if any.

offBits

Offset to brush bitmap bits, if any.

cbBits

Size of brush bitmap bits, if any.

elp

Extended logical pen, including the elpStyleEntry member of the EXTLOGPEN structure.

See Also

BITMAPINFO, ExtCreatePen, EXTLOGPEN


EMREXTFLOODFILL

typedef struct tagEMREXTFLOODFILL
{
    EMR     emr;

    POINTL  ptlStart;

    COLORREF crColor;

    DWORD   iMode;

} EMREXTFLOODFILL, *PEMREXTFLOODFILL;

The EMREXTFLOODFILL structure contains members for the ExtFloodFill enhanced metafile record.

Members

emr

Base structure for all record types.

ptlStart

Coordinates where filling begins.

crColor

Color of fill.

iMode

Type of fill operation to be performed. This member must be either the FLOODFILLBORDER or FLOODFILLSURFACE value.

See Also

ExtFloodFill


EMREXTSELECTCLIPRGN

typedef struct tagEMREXTSELECTCLIPRGN
{
    EMR   emr;

    DWORD cbRgnData;

    DWORD iMode;

    BYTE  RgnData[1]; //

} EMREXTSELECTCLIPRGN, *PEMREXTSELECTCLIPRGN;

The EMREXTSELECTCLIPRGN structure contains members for the ExtSelectClipRgn enhanced metafile record.

Members

emr

Base structure for all record types.

cbRgnData

Size of region data, in bytes.

iMode

Operation to be performed. This member must be one of the following values: RGN_AND, RGN_COPY, RGN_DIFF, RGN_OR, or RGN_XOR.

See Also

ExtSelectClipRgn


EMREXTTEXTOUTA, EMREXTTEXTOUTW

typedef struct tagEMREXTTEXTOUTA
{
    EMR     emr;

    RECTL   rclBounds;

    DWORD   iGraphicsMode;

    FLOAT   exScale;

    FLOAT   eyScale;
    EMRTEXT emrtext;

} EMREXTTEXTOUTA, *PEMREXTTEXTOUTA,
  EMREXTTEXTOUTW, *PEMREXTTEXTOUTW;

The EMREXTTEXTOUTA and EMREXTTEXTOUTW structures contain members for the ExtTextOut, TextOut, or DrawText enhanced metafile records.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

iGraphicsMode

Current graphics mode. This member can be either the GM_COMPATIBLE or GM_ADVANCED value.

exScale

X-scaling factor from page units to .01mm units if the graphics mode is the GM_COMPATIBLE value.

eyScale

Y-scaling factor from page units to .01mm units if the graphics mode is the GM_COMPATIBLE value.

emrtext

EMRTEXT structure, which is followed by the string and the intercharacter spacing array.

See Also

DrawText, ExtTextOut, TextOut, EMRTEXT


EMRFILLRGN

typedef struct tagEMRFILLRGN
{
    EMR   emr;

    RECTL rclBounds;

    DWORD cbRgnData;

    DWORD ihBrush;

    BYTE  RgnData[1];

} EMRFILLRGN, *PEMRFILLRGN;

The EMRFILLRGN structure contains members for the FillRgn enhanced metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cbRgnData

Size of region data, in bytes.

ihBrush

Index of brush, in handle table.

RgnData

Buffer containing RGNDATA structure.

See Also

FillRgn, RGNDATA


EMRFORMAT

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.

Members

dSignature

Contains a picture format identifier. The following identifier values are defined:

Identifier	Meaning
ENHMETA_SIGNATURE	The picture is in enhanced metafile format.
0x46535045	The picture is in encapsulated PostScript file format.
nVersion

Contains a picture version number. The following version number value is defined:

Version	Meaning
1	This is the version number of a level 1 encapsulated PostScript file.
cbData

Specifies the size, in bytes, of the picture data.

offData

Specifies an offset to the picture data. The offset is figured from the start of the GDICOMMENT_MULTIFORMATS public comment within which this EMRFORMAT structure is embedded. The offset must be a DWORD offset.

Remarks

GdiComment discusses enhanced metafile public comments in general, and the GDICOMMENT_MULTIFORMATS public comment in particular.

See Also

GdiComment


EMRFRAMERGN

typedef struct tagEMRFRAMERGN
{
    EMR   emr;

    RECTL rclBounds;

    DWORD cbRgnData;

    DWORD ihBrush;

    SIZEL szlStroke;

    BYTE  RgnData[1];

} EMRFRAMERGN, *PEMRFRAMERGN;

The EMRFRAMERGN structure contains members for the FrameRgn enhanced metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cbRgnData

Size of region data, in bytes.

ihBrush

Index of brush, in handle table.

szlStroke

Width and height of region frame.

RgnData

Buffer containing RGNDATA structure.

See Also

FrameRgn, RGNDATA


EMRGDICOMMENT

typedef struct tagEMRGDICOMMENT
{
    EMR   emr;

    DWORD cbData;

    BYTE  Data[1];

} EMRGDICOMMENT, *PEMRGDICOMMENT;

The EMRGDICOMMENT structure contains application-specific data. This enhanced metafile record is only meaningful to applications that know the format of the data and how to utilize it. This record is ignored by graphics device interface (GDI) during playback of the enhanced metafile.

Members

emr

Base structure for all record types.

cbData

Size of data buffer, in bytes.

Data[1]

Application-specific data.


EMRINVERTRGN, EMRPAINTRGN

typedef struct tagEMRINVERTRGN
{
    EMR   emr;

    RECTL rclBounds;

    DWORD cbRgnData;

    BYTE  RgnData[1];

} EMRINVERTRGN, *PEMRINVERTRGN,
  EMRPAINTRGN,  *PEMRPAINTRGN;

The EMRINVERTRGN and EMRPAINTRGN structures contain members for the InvertRgn and PaintRgn enhanced metafile records.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cbRgnData

Size of region data, in bytes.

RgnData

Buffer containing RGNDATA structure.

See Also

InvertRgn, PaintRgn


EMRLINETO, EMRMOVETOEX

typedef struct tagEMRLINETO
{
    EMR    emr;

    POINTL ptl;

} EMRLINETO,   *PEMRLINETO,
  EMRMOVETOEX, *PEMRMOVETOEX;

The EMRLINETO and EMRMOVETOEX structures contains members for the LineTo and MoveToEx enhanced metafile records.

Members

emr

Base structure for all record types.

ptl

Coordinates of the line's ending point for the LineTo function or coordinates of the new current position for the MoveToEx function.

See Also

LineTo, MoveToEx


EMRMASKBLT

typedef struct tagEMRMASKBLT
{
    EMR     emr;

    RECTL   rclBounds;

    LONG    xDest;

    LONG    yDest;

    LONG    cxDest;

    LONG    cyDest;

    DWORD   dwRop;

    LONG    xSrc;

    LONG    ySrc;

    XFORM   xformSrc;

    COLORREF crBkColorSrc;

    DWORD   iUsageSrc;

    DWORD   offBmiSrc;

    DWORD   cbBmiSrc;

    DWORD   offBitsSrc;

    DWORD   cbBitsSrc;

    LONG    xMask;

    LONG    yMask;

    DWORD   iUsageMask;

    DWORD   offBmiMask;

    DWORD   cbBmiMask;

    DWORD   offBitsMask;

    DWORD   cbBitsMask;

} EMRMASKBLT, *PEMRMASKBLT;

The EMRMASKBLT structure contains members for the MaskBlt enhanced metafile record. Note that graphics device interface (GDI) converts the device-dependent bitmap into a device-independent bitmap (DIB) before storing it in the metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

xDest

Logical x-coordinate of the upper-left corner of the destination rectangle.

yDest

Logical y-coordinate of the upper-left corner of the destination rectangle.

cxDest

Logical width of destination rectangle

cyDest

Logical height of destination rectangle

dwRop

Raster-operation code. These codes define how the color data of the source rectangle is to be combined with the color data of the destination rectangle to achieve the final color.

xSrc

Logical x-coordinate of the upper-left corner of the source rectangle.

ySrc

Logical y-coordinate of the upper-left corner of the source rectangle.

xformSrc

World-space to page-space transformation of the source device context.

crBkColorSrc

Background color (the RGB value) of the source device context.

iUsageSrc

Value of the bmiColors member of the source BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

xMask

Horizontal pixel offset into mask bitmap

yMask

Vertical pixel offset into mask bitmap

iUsageMask

Value of the bmiColors member of the mask BITMAPINFO structure.

offBmiMask

Offset to mask BITMAPINFO structure.

cbBmiMask

Size of mask BITMAPINFO structure.

offBitsMask

Offset to mask bitmap bits.

cbBitsMask

Size of mask bitmap bits.

See Also

BITMAPINFO, MaskBlt, RGB


EMRMODIFYWORLDTRANSFORM

typedef struct tagEMRMODIFYWORLDTRANSFORM
{
    EMR   emr;

    XFORM xform;

    DWORD iMode;

transformation
} EMRMODIFYWORLDTRANSFORM,
PEMRMODIFYWORLDTRANSFORM;

The EMRMODIFYWORLDTRANSFORM structure contains members for the ModifyWorldTransform enhanced metafile record.

Members

emr

Base structure for all record types.

xform

World-space to page-space transformation data.

iMode

Value specifying how the transformation data modifies the current world transformation. This member can be one of the following values: MWT_IDENTITY, MWT_LEFTMULTIPLY, or MWT_RIGHTMULTIPLY.

See Also

ModifyWorldTransform


EMROFFSETCLIPRGN

typedef struct tagEMROFFSETCLIPRGN
{
    EMR    emr;

    POINTL ptlOffset;

} EMROFFSETCLIPRGN, *PEMROFFSETCLIPRGN;

The EMROFFSETCLIPRGN structure contains members for the OffsetClipRgn enhanced metafile record.

Members

emr

Base structure for all record types.

ptlOffset

Logical coordinates of offset.

See Also

OffsetClipRgn


EMRPLGBLT

typedef struct tagEMRPLGBLT
{
    EMR      emr;

    RECTL    rclBounds;

    POINTL   aptlDest[3];

    LONG    xSrc;

    LONG    ySrc;

    LONG     cxSrc;

    LONG     cySrc;

    XFORM   xformSrc;

    COLORREF crBkColorSrc;

    DWORD    iUsageSrc;

    DWORD    offBmiSrc;

    DWORD   cbBmiSrc;

    DWORD   offBitsSrc;

    DWORD   cbBitsSrc;

    LONG    xMask;
    LONG    yMask;

    DWORD   iUsageMask;

    DWORD   offBmiMask;

    DWORD   cbBmiMask;
    DWORD   offBitsMask;
    DWORD   cbBitsMask;
} EMRPLGBLT, *PEMRPLGBLT;

The EMRPLGBLT structure contains members for the PlgBlt enhanced metafile record. Note that graphics device interface (GDI) converts the device-dependent bitmap into a device-independent bitmap (DIB) before storing it in the metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

aptlDest

Array of three points in logical space that identify three corners of the destination parallelogram. The upper-left corner of the source rectangle is mapped to the first point in this array, the upper-right corner to the second point in this array, and the lower-left corner to the third point. The lower-right corner of the source rectangle is mapped to the implicit fourth point in the parallelogram.

xSrc

Logical x-coordinate of the upper-left corner of the source rectangle.

ySrc

Logical y-coordinate of the upper-left corner of the source rectangle.

cxSrc

Logical width of source

cySrc

Logical height of source

xformSrc

World-space to page-space transformation of the source device context.

crBkColorSrc

Background color (the RGB value) of the source device context.

iUsageSrc

Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

xMask

Horizontal pixel offset into mask bitmap.

yMask

Vertical pixel offset into mask bitmap.

iUsageMask

Value of the bmiColors member of the mask BITMAPINFO structure.

offBmiMask

Offset to mask BITMAPINFO structure.

cbBmiMask

Size of mask BITMAPINFO structure.

offBitsMask

Offset to mask bitmap bits.

cbBitsMask

Size of mask bitmap bits.

See Also

BITMAPINFO, PlgBlt, RGB


EMRPOLYDRAW

typedef struct tagEMRPOLYDRAW
{
    EMR    emr;

    RECTL  rclBounds;

    DWORD  cptl;

    POINTL aptl[1];

    BYTE   abTypes[1];

} EMRPOLYDRAW, *PEMRPOLYDRAW;

The EMRPOLYDRAW structure contains members for the PolyDraw enhanced metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cptl

Number of points.

aptl

Array of 32-bit points.

abTypes

Array of values that specifies how each point in the aptl array is used. This member can be one of the following values: PT_MOVETO, PT_LINETO, or PT_BEZIERTO. The PT_LINETO or PT_BEZIERTO value can be combined with the PT_CLOSEFIGURE value by using the bitwise-xOR operator.

See Also

PolyDraw


EMRPOLYDRAW16

typedef struct tagEMRPOLYDRAW16
{
    EMR    emr;

    RECTL  rclBounds;

    DWORD  cpts;

    POINTS apts[1];

    BYTE   abTypes[1];

} EMRPOLYDRAW16, *PEMRPOLYDRAW16;

The EMRPOLYDRAW16 structure contains members for the PolyDraw enhanced metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cpts

Number of points.

apts

Array of 16-bit points.

abTypes

Array of values that specifies how each point in the apts array is used. This member can be one of the following values: PT_MOVETO, PT_LINETO, or PT_BEZIERTO. The PT_LINETO or PT_BEZIERTO value can be combined with the PT_CLOSEFIGURE value by using the bitwise-OR operator.

See Also

PolyDraw


EMRPOLYPOLYLINE, EMRPOLYPOLYGON

typedef struct tagEMRPOLYPOLYLINE
{
    EMR     emr;

    RECTL   rclBounds;

    DWORD   nPolys;

    DWORD   cptl;

    DWORD   aPolyCounts[1];

    POINTL  aptl[1];

} EMRPOLYPOLYLINE, *PEMRPOLYPOLYLINE,
  EMRPOLYPOLYGON,  *PEMRPOLYPOLYGON;

The EMRPOLYPOLYLINE and EMRPOLYPOLYGON structures contain members for the PolyPolyline and PolyPolygon enhanced metafile records.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

nPolys

Number of polys.

cpt1

Total number of points in all polys.

aPolyCounts

Array of point counts for each poly.

aptl

Array of 32-bit points.

See Also

PolyPolyline, PolyPolygon


EMRPOLYPOLYLINE16, EMRPOLYPOLYGON16

typedef struct tagEMRPOLYPOLYLINE16
{
    EMR     emr;

    RECTL   rclBounds;
    DWORD   nPolys;

    DWORD   cpts;

    DWORD   aPolyCounts[1];

    POINTS  apts[1];

} EMRPOLYPOLYLINE16, *PEMRPOLYPOLYLINE16,
  EMRPOLYPOLYGON16,  *PEMRPOLYPOLYGON16;

The EMRPOLYPOLYLINE16 and EMRPOLYPOLYGON16 structures contain members for the PolyPolyline and PolyPolygon enhanced metafile records.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

nPolys

Number of polys.

cpt1

Total number of points in all polys.

aPolyCounts

Array of point counts for each poly.

aptl

Array of 16-bit points.

See Also

PolyPolyline, PolyPolygon


EMRPOLYTEXTOUTA, EMRPOLYTEXTOUTW

typedef struct tagEMRPOLYTEXTOUTA
{
    EMR     emr;

    RECTL   rclBounds;

    DWORD   iGraphicsMode;

    FLOAT   exScale;

    FLOAT   eyScale;

    LONG    cStrings;

    EMRTEXT aemrtext[1];

} EMRPOLYTEXTOUTA, *PEMRPOLYTEXTOUTA,
  EMRPOLYTEXTOUTW, *PEMRPOLYTEXTOUTW;

The EMRPOLYTEXTOUTA and EMRPOLYTEXTOUTW structures contain members for the PolyTextOut enhanced metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

iGraphicsMode

Current graphics mode. This member can be either the GM_COMPATIBLE or GM_ADVANCED value.

exScale

X-scaling factor from page units to .01mm units if the graphics mode is the GM_COMPATIBLE value.

eyScale

Y-scaling factor from page units to .01mm units if the graphics mode is the GM_COMPATIBLE value.

cStrings

Number of strings.

aemrtext

EMRTEXT structure, which is followed by the string and the intercharacter spacing array.

See Also

EMRTEXT


EMRRESIZEPALETTE

typedef struct tagEMRRESIZEPALETTE
{
    EMR   emr;

    DWORD ihPal;

    DWORD cEntries;

} EMRRESIZEPALETTE, *PEMRRESIZEPALETTE;

The EMRRESIZEPALETTE structure contains members for the ResizePalette enhanced metafile record.

Members

emr

Base structure for all record types.

ihPal

Index of palette in handle table.

cEntries

Number of entries in palette after resizing.

See Also

ResizePalette


EMRRESTOREDC

typedef struct tagEMRRESTOREDC
{
    EMR  emr;

    LONG iRelative;

} EMRRESTOREDC, *PEMRRESTOREDC;

The EMRRESTOREDC structure contains members for the RestoreDC enhanced metafile record.

Members

emr

Base structure for all record types.

iRelative

Relative instance to restore.

See Also

RestoreDC


EMRROUNDRECT

typedef struct tagEMRROUNDRECT
{
    EMR   emr;

    RECTL rclBox;

    SIZEL szlCorner;

} EMRROUNDRECT, *PEMRROUNDRECT;

The EMRROUNDRECT structure contains members for the RoundRect enhanced metafile record.

Members

emr

Base structure for all record types.

szlCorner

Width and height of the ellipse used to draw rounded corners.

See Also

RoundRect


EMRSELECTOBJECT, EMRDELETEOBJECT

typedef struct tagEMRSELECTOBJECT
{
    EMR   emr;

    DWORD ihObject;
} EMRSELECTOBJECT, *PEMRSELECTOBJECT,
  EMRDELETEOBJECT, *PEMRDELETEOBJECT;

The EMRSELECTOBJECT and EMRDELETEOBJECT structures contain members for the SelectObject and DeleteObject enhanced metafile records.

Members

emr

Base structure for all record types.

ihObject

Index of object in handle table.

See Also

SelectObject, DeleteObject


EMRSELECTPALETTE

typedef struct tagEMRSELECTPALETTE

{
    EMR   emr;

    DWORD ihPal;

} EMRSELECTPALETTE, *PEMRSELECTPALETTE;

The EMRSELECTPALETTE structure contains members for the SelectPalette enhanced metafile record. Note that the bForceBackground parameter in SelectPalette is always recorded as TRUE, which causes the palette to be realized as a background palette.

Members

emr

Base structure for all record types.

ihPal

Index to logical palette in handle table.

See Also

SelectPalette


EMRSETARCDIRECTION

typedef struct tagEMRSETARCDIRECTION
{
    EMR   emr;

    DWORD iArcDirection;
} EMRSETARCDIRECTION, *PEMRSETARCDIRECTION;

The EMRSETARCDIRECTION structure contains members for the SetArcDirection enhanced metafile record.

Members

emr

Base structure for all record types.

iArcDirection

Arc direction. This member can be either the AD_CLOCKWISE or AD_COUNTERCLOCKWISE value.

See Also

Arc, SetArcDirection


EMRSETCOLORADJUSTMENT

typedef struct tagEMRSETCOLORADJUSTMENT
{
    EMR  emr;

    COLORADJUSTMENT ColorAdjustment;

} EMRSETCOLORADJUSTMENT, *PEMRSETCOLORADJUSTMENT;

The EMRSETCOLORADJUSTMENT structure contains members for the SetColorAdjustment enhanced metafile record.

Members

emr

Base structure for all record types.

ColorAdjustment

COLORADJUSTMENT structure.

See Also

SetColorAdjustment


EMRSETDIBITSTODEVICE

typedef struct tagEMRSETDIBITSTODEVICE
{
    EMR   emr;

    RECTL rclBounds;

    LONG  xDest;

    LONG  yDest;

    LONG  xSrc;

    LONG  ySrc;

    LONG  cxSrc;

    LONG  cySrc;

    DWORD offBmiSrc;

    DWORD cbBmiSrc;

    DWORD offBitsSrc;

    DWORD cbBitsSrc;

    DWORD iUsageSrc;

    DWORD iStartScan;

    DWORD cScans;

} EMRSETDIBITSTODEVICE, *PEMRSETDIBITSTODEVICE;

The EMRSETDIBITSTODEVICE structure contains members for the SetDIBitsToDevice enhanced metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

xDest

Logical x-coordinate of the upper-left corner of the destination rectangle.

yDest

Logical y-coordinate of the upper-left corner of the destination rectangle.

xSrc

Logical x-coordinate of the lower-left corner of the source device-independent bitmap (DIB).

ySrc

Logical y-coordinate of the lower-left corner of the source DIB.

cxSrc

Width of source rectangle.

cyScr

Height of source rectangle.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

iUsageSrc

Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

iStartScan

First scan line in array.

cScans

Number of scan lines.

See Also

BITMAPINFO, SetDIBitsToDevice


EMRSETMAPPERFLAGS

typedef struct tagEMRSETMAPPERFLAGS
{
    EMR   emr;

    DWORD dwFlags;

} EMRSETMAPPERFLAGS, *PEMRSETMAPPERFLAGS;

The EMRSETMAPPERFLAGS structure contains members for the SetMapperFlags enhanced metafile record.

Members

emr

Base structure for all record types.

dwFlags

Font mapper flag.

See Also

SetMapperFlags


EMRSETBKCOLOR, EMRSETTEXTCOLOR

typedef struct tagEMRSETTEXTCOLOR
{
    EMR      emr;

    COLORREF crColor;

} EMRSETBKCOLOR,   *PEMRSETBKCOLOR,
  EMRSETTEXTCOLOR, *PEMRSETTEXTCOLOR;

The EMRSETBKCOLOR and EMRSETTEXTCOLOR structures contain members for the SetBkColor and SetTextColor enhanced metafile records.

Members

emr

Base structure for all record types.

crColor

Color value.

See Also

SetBkColor, SetTextColor


EMRSETMITERLIMIT

typedef struct tagEMRSETMITERLIMIT
{
    EMR   emr;
    FLOAT eMiterLimit;

} EMRSETMITERLIMIT, *PEMRSETMITERLIMIT;

The EMRSETMITERLIMIT structure contains members for the SetMiterLimit enhanced metafile record.

Members

emr

Base structure for all record types.

eMiterLimit

New miter limit.

See Also

SetMiterLimit


EMRSETPALETTEENTRIES

typedef struct tagEMRSETPALETTEENTRIES
{
    EMR          emr;

    DWORD        ihPal;

    DWORD        iStart;

    DWORD        cEntries;

    PALETTEENTRY aPalEntries[1];

} EMRSETPALETTEENTRIES, *PEMRSETPALETTEENTRIES;

The EMRSETPALETTEENTRIES structure contains members for the SetPaletteEntries enhanced metafile record.

Members

emr

Base structure for all record types.

ihPal

Palette handle index.

iStart

Index of first entry to set.

cEntries

Number of entries.

aPalEntries

Array of PALETTEENTRY structures. Note that peFlags members in the structures do not contain any flags.

See Also

PALETTEENTRY, SetPaletteEntries


EMRSETPIXELV

typedef struct tagEMRSETPIXELV
{
    EMR     emr;

    POINTL  ptlPixel;

    COLORREF crColor;

} EMRSETPIXELV, *PEMRSETPIXELV;

The EMRSETPIXELV structure contains members for the SetPixelV enhanced metafile record. When an enhanced metafile is created, calls to SetPixel are also recorded in this record.

Members

emr

Base structure for all record types.

ptlPixel

Logical coordinates of pixel.

crColor

Color value.

SetPixelV, SetPixel


EMRSETWORLDTRANSFORM

typedef struct tagEMRSETWORLDTRANSFORM
{
    EMR   emr;

    XFORM xform;

} EMRSETWORLDTRANSFORM, *PEMRSETWORLDTRANSFORM;

The EMRSETWORLDTRANSFORM structure contains members for the SetWorldTransform enhanced metafile record.

Members

emr

Base structure for all record types.

xform

World-space to page-space transformation data.

See Also

SetWorldTransform


EMRSTRETCHDIBITS

typedef struct tagEMRSTRETCHDIBITS
{
    EMR   emr;
    RECTL rclBounds;

    LONG  xDest;

    LONG  yDest;

    LONG  xSrc;

    LONG  ySrc;

    LONG  cxSrc;

    LONG  cySrc;
    DWORD offBmiSrc;
    DWORD cbBmiSrc;

    DWORD offBitsSrc;

    DWORD cbBitsSrc;

    DWORD iUsageSrc;

    DWORD dwRop;

    LONG  cxDest;

    LONG  cyDest;

} EMRSTRETCHDIBITS, *PEMRSTRETCHDIBITS;

The EMRSTRETCHDIBITS structure contains members for the StretchDIBits enhanced metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

xDest

Logical x-coordinate of the upper-left corner of the destination rectangle.

yDest

Logical y-coordinate of the upper-left corner of the destination rectangle.

xSrc

Logical x-coordinate of the upper-left corner of the source rectangle.

ySrc

Logical y-coordinate of the upper-left corner of the source rectangle.

cxSrc

Width of source rectangle.

cyScr

Height of source rectangle.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

iUsageSrc

Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

dwRop

Raster-operation code. These codes define how the color data of the source rectangle is to be combined with the color data of the destination rectangle to achieve the final color.

cxDest

Logical width of destination rectangle

cyDest

Logical height of destination rectangle

See Also

BITMAPINFO, StretchDIBits


EMRSTRETCHBLT

typedef struct tagEMRSTRETCHBLT
{
    EMR      emr;

    RECTL    rclBounds;

    LONG     xDest;

    LONG     yDest;

    LONG     cxDest;

    LONG     cyDest;

    DWORD    dwRop;

    LONG     xSrc;

    LONG     ySrc;

    XFORM    xformSrc;

    COLORREF crBkColorSrc;

    DWORD    iUsageSrc;

    DWORD    offBmiSrc;

    DWORD    cbBmiSrc;

    DWORD    offBitsSrc;

    DWORD    cbBitsSrc;

    LONG     cxSrc;

    LONG     cySrc;

} EMRSTRETCHBLT, *PEMRSTRETCHBLT;

The EMRSTRETCHBLT structure contains members for the StretchBlt enhanced metafile record. Note that graphics device interface (GDI) converts the device-dependent bitmap into a device-independent bitmap (DIB) before storing it in the metafile record.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

xDest

Logical x-coordinate of the upper-left corner of the destination rectangle.

yDest

Logical y-coordinate of the upper-left corner of the destination rectangle.

cxDest

Logical width of destination rectangle

cyDest

Logical height of destination rectangle

dwRop

Raster-operation code. These codes define how the color data of the source rectangle is to be combined with the color data of the destination rectangle to achieve the final color.

xSrc

Logical x-coordinate of the upper-left corner of the source rectangle.

ySrc

Logical y-coordinate of the upper-left corner of the source rectangle.

xformSrc

World-space to page-space transformation of the source device context.

crBkColorSrc

Background color (the RGB value) of the source device context.

iUsageSrc

Value of the bmiColors member of the BITMAPINFO structure. The iUsageSrc member can be either the DIB_PAL_COLORS, DIB_PAL_INDICES, or DIB_RGB_COLORS value.

offBmiSrc

Offset to source BITMAPINFO structure.

cbBmiSrc

Size of source BITMAPINFO structure.

offBitsSrc

Offset to source bitmap bits.

cbBitsSrc

Size of source bitmap bits.

cxSrc

Width of source rectangle.

cySrc

Height of source rectangle.

See Also

BITMAPINFO, RGB, StretchBlt


EMRTEXT

typedef struct tagEMRTEXT

{
    POINTL ptlReference;

    DWORD  nChars;

    DWORD  offString;

    DWORD  fOptions;

    RECTL  rcl;

    DWORD  offDx;

} EMRTEXT, *PEMRTEXT;

The EMRTEXT structure contains members for text output.

Members

ptlReference

Logical coordinates of the reference point used to position the string.

nChars

Number of characters in string.

offString

Offset to string.

fOptions

Value specifying how to use the application-defined rectangle. This member can be a combination of the ETO_CLIPPED and ETO_OPAQUE values.

rcl

Optional clipping and/or opaquing rectangle.

offDx

Offset to intercharacter spacing array.

Remarks

The EMRTEXT structure is used as a member in the EMREXTTEXTOUT and EMRPOLYTEXTOUT structures.


Enhanced Metafile Records with No Parameters

typedef struct tagABORTPATH

{

    EMR emr;

} EMRABORTPATH,      *PEMRABORTPATH,
  EMRBEGINPATH,      *PEMRBEGINPATH,
  EMRENDPATH,        *PEMRENDPATH,
  EMRCLOSEFIGURE,    *PEMRCLOSEFIGURE,
  EMRFLATTENPATH,    *PEMRFLATTENPATH,
  EMRWIDENPATH,      *PEMRWIDENPATH,
  EMRSETMETARGN,     *PEMRSETMETARGN,
  EMRSAVEDC,         *PEMRSAVEDC,
  EMRREALIZEPALETTE, *PEMRREALIZEPALETTE;

Contains data for the AbortPath, BeginPath, EndPath, CloseFigure, FlattenPath, WidenPath, SetMetaRgn, SaveDC, and RealizePalette enhanced metafile records.


Enhanced Metafile Records with One Parameter

typedef struct tagEMRSELECTCLIPPATH
{
    EMR   emr;

    DWORD iMode;

} EMRSELECTCLIPPATH,    *PEMRSELECTCLIPPATH,
  EMRSETBKMODE,         *PEMRSETBKMODE,
  EMRSETMAPMODE,        *PEMRSETMAPMODE,
  EMRSETPOLYFILLMODE,   *PEMRSETPOLYFILLMODE,
  EMRSETROP2,           *PEMRSETROP2,
  EMRSETSTRETCHBLTMODE, *PEMRSETSTRETCHBLTMODE,
  EMRSETTEXTALIGN,	      *PEMRSETTEXTALIGN,
  EMRENABLEICM, 	      *PEMRENABLEICM

Contains parameters for the SelectClipPath, SetBkMode, SetPolyFillMode, SetROP2, SetStretchBltMode, SetTextAlign, and EnableICM enhanced metafile records.

Members

emr

Base structure for all record types.

iMode

Value and meaning that varies depending on the function contained in the enhanced metafile record. For a description of this member, see the documentation of the functions contained in this record .

See Also

SelectClipPath, SetBkMode, SetPolyFillMode, SetROP2, SetStretchBltMode, SetTextAlign


EMRFILLPATH, EMRSTROKEANDFILLPATH, EMRSTROKEPATH

typedef struct tagEMRFILLPATH
{
    EMR   emr;

    RECTL rclBounds;

} EMRFILLPATH,          *PEMRFILLPATH,
  EMRSTROKEANDFILLPATH, *PEMRSTROKEANDFILLPATH,
  EMRSTROKEPATH,        *PEMRSTROKEPATH;

The EMRFILLPATH, EMRSTROKEANDFILLPATH, and EMRSTROKEPATH structures contain members for the FillPath, StrokeAndFillPath, and StrokePath enhanced metafile records.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

See Also

FillPath, StrokeAndFillPath, StrokePath


EMRPOLYLINE, EMRPOLYBEZIER, EMRPOLYGON, EMRPOLYBEZIERTO, EMRPOLYLINETO
EMRPOLYLINE, EMRPOLYBEZIER, EMRPOLYGON, EMRPOLYBEZIERTO, EMRPOLYLINETO  (preliminary−Windows 95)

typedef struct tagEMRPOLYLINE
{
    EMR    emr;
    RECTL  rclBounds;

    DWORD  cptl;

    POINTL aptl[1];

} EMRPOLYLINE,     *PEMRPOLYLINE,
  EMRPOLYBEZIER,   *PEMRPOLYBEZIER,
  EMRPOLYGON,      *PEMRPOLYGON,
  EMRPOLYBEZIERTO, *PEMRPOLYBEZIERTO,
  EMRPOLYLINETO,   *PEMRPOLYLINETO;

The EMRPOLYLINE, EMRPOLYBEZIER, EMRPOLYGON, EMRPOLYBEZIERTO, and EMRPOLYLINETO structures contain members for the Polyline, PolyBezier, Polygon, PolyBezierTo, and PolylineTo enhanced metafile records.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cptl

Number of points array.

aptl

Array of 32-bit points.

See Also

PolyBezier, PolyBezierTo, Polygon, Polyline, PolylineTo


EMRPOLYLINE16, EMRPOLYBEZIER16, EMRPOLYGON16, EMRPOLYBEZIERTO16, EMRPOLYLINETO16

typedef struct tagEMRPOLYLINE
{
    EMR    emr;

    RECTL  rclBounds;

    DWORD  cpts;

    POINTL apts[1];

} EMRPOLYLINE16,     *PEMRPOLYLINE16,
  EMRPOLYBEZIER16,   *PEMRPOLYBEZIER16,
  EMRPOLYGON16,      *PEMRPOLYGON16,
  EMRPOLYBEZIERTO16, *PEMRPOLYBEZIERTO16,
  EMRPOLYLINETO16,   *PEMRPOLYLINETO16;

The EMRPOLYLINE16, EMRPOLYBEZIER16, EMRPOLYGON16, EMRPOLYBEZIERTO16, and EMRPOLYLINETO16 structures contain members for the Polyline, PolyBezier, Polygon, PolyBezierTo, and PolylineTo enhanced metafile records.

Members

emr

Base structure for all record types.

rclBounds

Bounding rectangle, in device units.

cpts

Number of points in the array.

apts

Array of 16-bit points.

See Also

PolyBezier, PolyBezierTo, Polygon, Polyline, PolylineTo


EMRSCALEVIEWPORTEXTEX, EMRSCALEWINDOWEXTEX

typedef struct tagEMRSCALEVIEWPORTEXTEX
{
    EMR  emr;

    LONG xNum;

    LONG xDenom;

    LONG yNum;

    LONG yDenom;

} EMRSCALEVIEWPORTEXTEX, *PEMRSCALEVIEWPORTEXTEX,

  EMRSCALEWINDOWEXTEX,   *PEMRSCALEWINDOWEXTEX;

The EMRSCALEVIEWPORTEXTEX and EMRSCALEWINDOWEXTEX structures contain members for the ScaleViewportExtEx and ScaleWindowExtEx enhanced metafile records.

Members

emr

Base structure for all record types.

xNum

Horizontal multiplicand.

xDenom

Horizontal divisor.

yNum

Vertical multiplicand.

yDenom

Vertical divisor.

See Also

ScaleViewportExtEx, ScaleWindowExtEx


EMRSELECTCOLORSPACE, EMRDELETECOLORSPACE  (preliminaryWindows 95)
EMRSELECTCOLORSPACE, EMRDELETECOLORSPACE  (preliminary−Windows 95)

typedef struct tagEMRSELECTCOLORSPACE

{

    EMR     emr;

    DWORD   ihCS;

} EMRSELECTCOLORSPACE, *PEMRSELECTCOLORSPACE,
  EMRDELETECOLORSPACE, *PEMRDELETECOLORSPACE;

The EMRSELECTCOLORSPACE and EMRDELETECOLORSPACE structures contain members for the SelectColorSpace and DeleteColorSpace enhanced metafile records.

Members

emr

Base structure for all record types.

ihCS

Color space handle index.

See Also

DeleteColorSpace


EMRSETVIEWPORTORGEX, EMRSETWINDOWORGEX, EMRSETBRUSHORGEX

typedef struct tagEMRSETVIEWPORTORGEX
{
    EMR    emr;

    POINTL ptlOrigin;

} EMRSETVIEWPORTORGEX, *PEMRSETVIEWPORTORGEX,
  EMRSETWINDOWORGEX,   *PEMRSETWINDOWORGEX,
  EMRSETBRUSHORGEX,    *PEMRSETBRUSHORGEX;

The EMRSETVIEWPORTORGEX, EMRSETWINDOWORGEX, and EMRSETBRUSHORGEX structures contain members for the SetViewportOrgEx, SetWindowOrgEx, and SetBrushOrgEx enhanced metafile records.

Members

emr

Base structure for all record types.

ptlOrigin

Coordinate of origin.

See Also

SetBrushOrgEx, SetViewportOrgEx, SetWindowOrgEx


EMRSETVIEWPORTEXTEX, EMRSETWINDOWEXTEX

typedef struct tagEMRSETVIEWPORTEXTEX
{
    EMR   emr;

    SIZEL szlExtent;

} EMRSETVIEWPORTEXTEX, *PEMRSETVIEWPORTEXTEX,
  EMRSETWINDOWEXTEX,   *PEMRSETWINDOWEXTEX;

The EMRSETVIEWPORTEXTEX and EMRSETWINDOWEXTEX structures contains members for the SetViewportExtEx and SetWindowExtEx enhanced metafile records.

Members

emr

Base structure for all record types.

szlExtent

Horizontal and vertical extents. For SetViewportExtEx, the extents are in device units, and for SetWindowExtEx, the extents are in logical units.

SetViewportExtEx, SetWindowExtEx


ENDROPFILES  (preliminaryWindows NT)
ENDROPFILES  (preliminary−Windows NT)

typedef struct _endropfiles {

    NMHDR nmhdr;

    HANDLE hDrop;

    LONG cp;

    BOOL fProtected;

} ENDROPFILES;

The ENDDROPFILES structure contains information associated with an EN_DROPFILES notification message. A rich edit control sends this notification message when it receives a WM_DROPFILES message.

Members

nmhdr

Notification header.

hDrop

Handle to the dropped files list (same as with WM_DROPFILES). This handle is used with the DragFinish, DragQueryFile, and DragQueryPoint functions.

cp

Character position at which the dropped files would be inserted.

fProtected

Boolean value specifying whether the specified character position is protected (TRUE) or not protected (FALSE).

See Also

DragFinish, DragQueryFile, DragQueryPoint, EN_DROPFILES, WM_DROPFILES


ENHMETAHEADER

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.

Members

iType

Specifies the record type. This member must specify the value assigned to the EMR_HEADER constant.

nSize

Specifies the structure size, in bytes.

rclBounds

Specifies the dimensions, in device units, of the smallest rectangle that can be drawn around the picture stored in the metafile. This rectangle is supplied by graphics device interface (GDI). Its dimensions include the right and bottom edges.

rclFrame

Specifies the dimensions, in .01 millimeter units, of a rectangle that surrounds the picture stored in the metafile. This rectangle must be supplied by the application that creates the metafile. Its dimensions include the right and bottom edges.

dSignature

Specifies a doubleword signature. This member must specify the value assigned to the ENHMETA_SIGNATURE constant.

nVersion

Specifies the metafile version. The current version value is 0x10000.

nBytes

Specifies the size of the enhanced metafile, in bytes.

nRecords

Specifies the number of records in the enhanced metafile.

nHandles

Specifies the number of handles in the enhanced-metafile handle table. (Index zero in this table is reserved.)

sReserved

Reserved; must be zero.

nDescription

Specifies the number of characters in the array that contains the description of the enhanced metafile's contents. This member should be set to zero if the enhanced metafile does not contain a description string.

offDescription

Specifies the offset from the beginning of the ENHMETAHEADER structure to the array that contains the description of the enhanced metafile's contents. This member should be set to zero if the enhanced metafile does not contain a description string.

nPalEntries

Specifies the number of entries in the enhanced metafile's palette.

szlDevice

Specifies the resolution of the reference device, in pixels.

szlMillimeters

Specifies the resolution of the reference device, in millimeters.

See Also

ENHMETARECORD


ENHMETARECORD

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.

Members

iType

Specifies the record type.

nSize

Specifies the size of the record, in bytes.

dParm

Specifies an array of parameters passed to the GDI function identified by the record.

See Also

ENHMETAHEADER


ENPROTECTED  (preliminaryWindows NT)
ENPROTECTED  (preliminary−Windows NT)

typedef struct _enprotected {

    NMHDR nmhdr;

    _WPAD _wPad1;

    UINT msg;

    _WPAD _wPad2;

    WPARAM wParam;

    LPARAM lParam;

    CHARRANGE chrg;

} ENPROTECTED;

The ENPROTECTED structure contains information associated with an EN_PROTECTED notification message. A rich edit control sends this notification when the user attempts to edit protected text.

Members

nmhdr

Notification header.

msg

Message that triggered the notification.

wParam

wParam parameter of the message.

lParam

lParam parameter of the message.

chrg

Current selection.

See Also

EN_PROTECTED


ENUMLOGFONT

typedef struct tagENUMLOGFONT { // elf

    LOGFONT elfLogFont;

    BCHAR    elfFullName[LF_FULLFACESIZE];

    BCHAR    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.

Members

elfLogFont

Specifies a LOGFONT structure that defines the attributes of a font.

elfFullName

Specifies a unique name for the font. For example, "ABCD Font Company TrueType Bold Italic Sans Serif".

elfStyle

Specifies the style of the font. For example, "Bold Italic".

See Also

EnumFontFamProc, LOGFONT


ENUMLOGFONTEX  (preliminaryWindows 95)
ENUMLOGFONTEX  (preliminary−Windows 95)

typedef struct tagENUMLOGFONTEX {
    LOGFONT  elfLogFont;
    BCHAR  elfFullName[LF_FULLFACESIZE];
    BCHAR  elfStyle[LF_FACESIZE];
    BCHAR  elfScript[LF_FACESIZE];
} ENUMLOGFONTEX;

The ENUMLOGFONTEX structure contains information about an enumerated font.

Members

elfLogFont

Specifies a LOGFONT structure that contains values defining the font attributes.

elfFullName

Specifies a null-terminated string specifying the unique name of the font. For example, "ABC Font Company TrueType Bold Italic Sans Serif".

elfStyle

Specifies a null-terminated string specifying the style of the font. For example, "Bold Italic".

elfScript

Specifies a null-terminated string specifying the script of the font. For example, "Cyrillic".

See Also

EnumFontFamExProc, EnumFontFamiliesEx, LOGFONT


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.

Members

lpServiceName

Points to a null-terminated string that names a service in a service control manager database. The maximum string length is 256 characters. The service control manager database preserves the case of the characters, but service name comparisons are always case insensitive. A slash (/), backslash (\), comma, and space are invalid service name characters.

lpDisplayName

Points to a null-terminated string that is to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the Service Control Manager. Display name comparisons are always case-insensitive.

ServiceStatus

Specifies a SERVICE_STATUS structure in which status information about the lpServiceName service is returned.

See Also

EnumDependentServices, EnumServicesStatus, SERVICE_STATUS


EVENTLOGRECORD

typedef struct _EVENTLOGRECORD { // evlr

    DWORD  Length;

    DWORD  Reserved;

    DWORD  RecordNumber;

    DWORD  TimeGenerated;

    DWORD  TimeWritten;

    DWORD  EventID;

    WORD   EventType;

    WORD   NumStrings;

    WORD   EventCategory;

    WORD   ReservedFlags;

    DWORD  ClosingRecordNumber;

    DWORD  StringOffset;

    DWORD  UserSidLength;

    DWORD  UserSidOffset;

    DWORD  DataLength;

    DWORD  DataOffset;

    //

    // Then follow:

    //

    // TCHAR SourceName[]

    // TCHAR Computername[]

    // SID   UserSid

    // TCHAR Strings[]

    // BYTE  Data[]

    // CHAR  Pad[]

    // DWORD Length;

    //

} EVENTLOGRECORD;

The EVENTLOGRECORD structure contains information about an event record.

Members

Length

Specifies the length, in bytes, of this event record. Note that this value is stored at both ends of the entry to ease moving forward or backward through the log. The length includes any pad bytes inserted at the end of the record for DWORD alignment.

Reserved

Reserved.

RecordNumber

Contains a record number that can be used with the EVENTLOG_SEEK_READ flag passed in a call to the ReadEventLog function to begin reading at a specified record.

TimeGenerated

The time at which this entry was submitted. This time is measured in the number of seconds elapsed since 00:00:00 January 1, 1970.

TimeWritten

Specifies the time at which this entry was received by the service to be written to the logfile. This time is measured in the number of seconds elapsed since 00:00:00 January 1, 1970.

EventID

Identifies the event. This is specific to the source that generated the event log entry, and is used, together with SourceName, to identify a message in a message file that is presented to the user while viewing the log.

EventType

Specifies the type of event. This member can be one of the following values:

Value	Meaning
EVENTLOG_ERROR_TYPE	Error event
EVENTLOG_WARNING_TYPE	Warning event
EVENTLOG_INFORMATION_TYPE	Information event
EVENTLOG_AUDIT_SUCCESS	Success Audit event
EVENTLOG_AUDIT_FAILURE	Failure Audit event
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

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.

Members

message

Specifies the message.

paramL

Specifies additional information about the message. The exact meaning depends on the message value.

paramH

Specifies additional information about the message. The exact meaning depends on the message value.

time

Specifies the time at which the message was posted.

hwnd

Identifies the window to which the message was posted.

See Also

JournalPlaybackProc, SetWindowsHookEx


EXCEPTION_DEBUG_INFO

typedef struct _EXCEPTION_DEBUG_INFO { // exdi

    EXCEPTION_RECORD ExceptionRecord;

    DWORD dwFirstChance;

} EXCEPTION_DEBUG_INFO;

The EXCEPTION_DEBUG_INFO structure contains exception information that can be used by a debugger.

Members

ExceptionRecord

Contains an EXCEPTION_RECORD structure with information specific to the exception. This includes the exception code, flags, address, a pointer to a related exception, extra parameters, and so on.

dwFirstChance

Indicates whether the debugger has previously encountered the exception specified by the ExceptionRecord member. If the dwFirstChance member is nonzero, this is the first time the debugger has encountered the exception. Debuggers typically handle breakpoint and single-step exceptions when they are first encountered. If this member is zero, the debugger has previously encountered the exception. This occurs only if, during the search for structured exception handlers, either no handler was found or the exception was continued.

See Also

DEBUG_EVENT, EXCEPTION_RECORD


EXCEPTION_POINTERS

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.

Members

ExceptionRecord

Points to an EXCEPTION_RECORD structure that contains a machine-independent description of the exception.

ContextRecord

Points to a CONTEXT structure that contains a processor-specific description of the state of the processor at the time of the exception.

See Also

GetExceptionInformation, CONTEXT, EXCEPTION_RECORD


EXCEPTION_RECORD

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.

Members

ExceptionCode

Specifies the reason the exception occurred. This is the code generated by a hardware exception, or the code specified in the RaiseException function for a software-generated exception. Following are the exception codes likely to occur due to common programming errors:

Value	Meaning
EXCEPTION_ACCESS_VIOLATION
	The thread tried to read from or write to a virtual address for which it does not have the appropriate access.
EXCEPTION_ARRAY_BOUNDS_EXCEEDED
	The thread tried to access an array element that is out of bounds and the underlying hardware supports bounds checking.
EXCEPTION_BREAKPOINT
	A breakpoint was encountered.
EXCEPTION_DATATYPE_MISALIGNMENT
	The thread tried to read or write data that is misaligned on hardware that does not provide alignment. For example, 16-bit values must be aligned on 2-byte boundaries; 32-bit values on 4-byte boundaries, and so on.
EXCEPTION_FLT_DENORMAL_OPERAND
	One of the operands in a floating-point operation is denormal. A denormal value is one that is too small to represent as a standard floating-point value.
EXCEPTION_FLT_DIVIDE_BY_ZERO
	The thread tried to divide a floating-point value by a floating-point divisor of zero.
EXCEPTION_FLT_INEXACT_RESULT
	The result of a floating-point operation cannot be represented exactly as a decimal fraction.
EXCEPTION_FLT_INVALID_OPERATION
	This exception represents any floating-point exception not included in this list.
EXCEPTION_FLT_OVERFLOW
	The exponent of a floating-point operation is greater than the magnitude allowed by the corresponding type.
EXCEPTION_FLT_STACK_CHECK
	The stack overflowed or underflowed as the result of a floating-point operation.
EXCEPTION_FLT_UNDERFLOW
	The exponent of a floating-point operation is less than the magnitude allowed by the corresponding type.
EXCEPTION_ILLEGAL_INSTRUCTION
	The thread tried to execute an invalid instruction.
EXCEPTION_IN_PAGE_ERROR
	The thread tried to access a page that was not present, and the system was unable to load the page. For example, this exception might occur if a network connection is lost while running a program over the network.
EXCEPTION_INT_DIVIDE_BY_ZERO
	The thread tried to divide an integer value by an integer divisor of zero.
EXCEPTION_INT_OVERFLOW
	The result of an integer operation caused a carry out of the most significant bit of the result.
EXCEPTION_INVALID_DISPOSITION
	An exception handler returned an invalid disposition to the exception dispatcher. Programmers using a high-level language such as C should never encounter this exception.
EXCEPTION_NONCONTINUABLE_EXCEPTION
	The thread tried to continue execution after a noncontinuable exception occurred.
EXCEPTION_PRIV_INSTRUCTION
	The thread tried to execute an instruction whose operation is not allowed in the current machine mode.
EXCEPTION_SINGLE_STEP
	A trace trap or other single-instruction mechanism signaled that one instruction has been executed.
EXCEPTION_STACK_OVERFLOW
	The thread used up its stack.
Another exception code is likely to occur when debugging console processes. It does not arise because of a programming error. The DBG_CONTROL_C exception code occurs when Ctrl+C is input to a console process that handles Ctrl+C signals and is being debugged. This exception code is not meant to be handled by applications. It is raised only for the benefit of the debugger, and is raised only when a debugger is attached to the console process.

ExceptionFlags

Specifies the exception flags. This member can be either zero, indicating a continuable exception, or EXCEPTION_NONCONTINUABLE indicating a noncontinuable exception. Any attempt to continue execution after a noncontinuable exception causes the EXCEPTION_NONCONTINUABLE_EXCEPTION exception.

ExceptionRecord

Points to an associated EXCEPTION_RECORD structure. Exception records can be chained together to provide additional information when nested exceptions occur.

ExceptionAddress

Specifies the address where the exception occurred.

NumberParameters

Specifies the number of parameters associated with the exception. This is the number of defined elements in the ExceptionInformation array.

ExceptionInformation

Specifies an array of additional 32-bit arguments that describe the exception. The RaiseException function can specify this array of arguments. For most exception codes, the array elements are undefined. For the following exception code, the array elements are defined as follows:

Exception code	Array contents
EXCEPTION_ACCESS_VIOLATION
	The first element of the array contains a read-write flag that indicates the type of operation that caused the access violation. If this value is zero, the thread attempted to read the inaccessible data. If this value is 1, the thread attempted to write to an inaccessible address.
	The second array element specifies the virtual address of the inaccessible data.
See Also

EXCEPTION_DEBUG_INFO, EXCEPTION_POINTERS, GetExceptionInformation, RaiseException, UnhandledExceptionFilter


EXIT_PROCESS_DEBUG_INFO

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.

Members

dwExitCode

Specifies the exit code for the process.

See Also

DEBUG_EVENT


EXIT_THREAD_DEBUG_INFO

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.

Members

dwExitCode

Specifies the exit code for the thread.

See Also

DEBUG_EVENT


EXT_BUTTON

typedef struct _EXT_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.

Members

idCommand

Specifies the command identifier for the button.

idsHelp

Specifies the identifier of the Help string for the button.

fsStyle

Specifies the style of the button.

See Also

FMEVENT_TOOLBARLOAD, FMS_TOOLBARLOAD


EXTLOGFONT

typedef struct tagEXTLOGFONT {

    LOGFONT elfLogFont;

    BCHAR    elfFullName[LF_FULLFACESIZE];

    BCHAR    elfStyle[LF_FACESIZE];

    DWORD   elfVersion;

    DWORD   elfStyleSize;

    DWORD   elfMatch;

    DWORD   elfReserved;

    BYTE    elfVendorId[ELF_VENDOR_SIZE];

    DWORD   elfCulture;

    PANOSE  elfPanose;

} EXTLOGFONT;

The EXTLOGFONT structure defines the attributes of a font.

Members

elfLogFont

Specifies some of the attributes of the given font. This member is a LOGFONT structure.

elfFullName

Specifies a unique name for the font (for example, ABCD Font Company TrueType Bold Italic Sans Serif).

elfStyle

Specifies the style of the font (for example, Bold Italic).

elfVersion

Reserved. Must be zero.

elfStyleSize

This member only has meaning for hinted fonts. It specifies the point size at which the font is hinted. If set to zero, which is its default value, the font is hinted at the point size corresponding to the lfHeight member of the LOGFONT structure specified by elfLogFont.

elfMatch

A unique identifier for an enumerated font. This will be filled in by the graphics device interface (GDI) upon font enumeration.

elfReserved

Reserved; must be zero.

elfVendorId

A 4-byte identifier of the font vendor.

elfCulture

Reserved; must be zero.

elfPanose

A PANOSE structure that specifies the shape of the font. If all members of this structure are set to zero, the elfPanose member is ignored by the font mapper.

See Also

LOGFONT, PANOSE


EXTLOGPEN

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.

Members

elpPenStyle

Specifies a combination of pen type, style, end cap style, and join style. The values from each category can be retrieved by using a bitwise AND with the appropriate mask.

The elpPenStyle member masked with PS_TYPE_MASK has one of the following pen type values:

Value	Meaning
PS_GEOMETRIC	The pen is geometric.
PS_COSMETIC	The pen is cosmetic.
The elpPenStyle member masked with PS_STYLE_MASK has one of the following pen styles values:

Value	Meaning
PS_SOLID	The pen is solid.
PS_DASH	The pen is dashed.
PS_DOT	The pen is dotted.
PS_DASHDOT	The pen has alternating dashes and dots.
PS_DASHDOTDOT	The pen has alternating dashes and double dots.
PS_NULL	The pen is invisible.
PS_USERSTYLE	The pen will use a styling array supplied by the user.
PS_INSIDEFRAME	The pen is solid. When this pen is used in any GDI drawing function that takes a bounding rectangle, the dimensions of the figure are shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. This applies only to PS_GEOMETRIC pens.
The following category applies only to PS_GEOMETRIC pens. The elpPenStyle member masked with PS_ENDCAP_MASK has one of the following end cap values:

Value	Meaning
PS_ENDCAP_ROUND	Line end caps are round.
PS_ENDCAP_SQUARE	Line end caps are square.
PS_ENDCAP_FLAT	Line end caps are flat.
The following category applies only to PS_GEOMETRIC pens. The elpPenStyle member masked with PS_JOIN_STYLE has one of the following join values:

Value	Meaning
PS_JOIN_BEVEL	Line joins are beveled.
PS_JOIN_MITER	Line joins are mitered when they are within the current SetMiterLimit limit. A join is beveled when it would exceed the limit.
PS_JOIN_ROUND	Line joins are round.
elpWidth

Specifies the width of the pen. If the elpPenStyle member specifies geometric lines, this value is the width, in logical units, of the line. Otherwise, the lines are cosmetic and this value is 1.

elpBrushStyle

Specifies the brush style of the pen. The elpBrushStyle member values can be one of the following:

Value	Description
BS_DIBPATTERN	Specifies a pattern brush defined by a device-independent bitmap (DIB) specification. If elpBrushStyle is BS_DIBPATTERN, the elpHatch member contains a handle to a packed DIB.
BS_DIBPATTERNPT	Specifies a pattern brush defined by a device-independent bitmap (DIB) specification. If elpBrushStyle is BS_DIBPATTERNPT, the elpHatch member contains a pointer to a packed DIB.
BS_HATCHED	Specifies a hatched brush.
BS_HOLLOW	Specifies a hollow or NULL brush.
BS_PATTERN	Specifies a pattern brush defined by a memory bitmap.
BS_SOLID	Specifies a solid brush.
elpColor

If elpBrushStyle is BS_SOLID or BS_HATCHED, elpColor specifies the color in which the pen is to be drawn. For BS_HATCHED, the SetBkMode and SetBkColor functions determine the background color.

If elpBrushStyle is BS_HOLLOW or BS_PATTERN, elpColor is ignored.

If elpBrushStyle is BS_DIBPATTERN or BS_DIBPATTERNPT, the low-order word of elpColor specifies whether the bmiColors members of the BITMAPINFO structure contain explicit red, green, blue (RGB) values or indexes into the currently realized logical palette. The elpColor value must be one of the following:

Value	Meaning
DIB_PAL_COLORS	The color table consists of an array of 16-bit indexes into the currently realized logical palette.
DIB_RGB_COLORS	The color table contains literal RGB values.
elpHatch

If elpBrushStyle is BS_PATTERN, elpHatch is a handle to the bitmap that defines the pattern.

If elpBrushStyle is BS_SOLID or BS_HOLLOW, elpHatch is ignored.

If elpBrushStyle is BS_DIBPATTERN, the elpHatch member is a handle to a packed DIB. To obtain this handle, an application calls the GlobalAlloc function to allocate a block of global memory and then fills the memory with the packed DIB. A packed DIB consists of a BITMAPINFO structure immediately followed by the array of bytes that define the pixels of the bitmap.

If elpBrushStyle is BS_DIBPATTERNPT, the elpHatch member is a pointer to a packed DIB.

If elpBrushStyle is BS_HATCHED, the elpHatch member specifies the orientation of the lines used to create the hatch. It can be any one of the following values:

Value	Meaning
HS_BDIAGONAL	45-degree upward hatch (left to right)
HS_CROSS	Horizontal and vertical crosshatch
HS_DIAGCROSS	45-degree crosshatch
HS_FDIAGONAL	45-degree downward hatch (left to right)
HS_HORIZONTAL	Horizontal hatch
HS_VERTICAL	Vertical hatch
elpNumEntries

Specifies the number of entries in the style array in the elpStyleEntry member. This value is zero if elpPenStyle does not specify PS_USERSTYLE.

elpStyleEntry

Specifies a user-supplied style array. The array is specified with a finite length, but it is used as if it repeated indefinitely. The first entry in the array specifies the length of the first dash. The second entry specifies the length of the first gap. Thereafter, lengths of dashes and gaps alternate.

If elpWidth specifies geometric lines, the lengths are in logical units. Otherwise, the lines are cosmetic and lengths are in device units.

See Also

BITMAPINFO, ExtCreatePen, GetObject, GlobalAlloc, SetBkColor, SetBkMode


FILETIME

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.

Members

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


FILTERKEYS

typedef struct tagFILTERKEYS {     // fk

    UINT  cbSize;

    DWORD dwFlags;

    DWORD iWaitMSec;

    DWORD iDelayMSec;

    DWORD iRepeatMSec;

    DWORD iBounceMSec;

} FILTERKEYS;

The FILTERKEYS structure contains information about the FilterKeys accessibility feature, which allow a user with disabilities to set the keyboard repeat rate (RepeatKeys), acceptance delay (SlowKeys), and bounce rate (BounceKeys).

Members

cbSize

Specifies the structure size, in bytes.

dwFlags

A set of bit flags that specify properties of the FilterKeys feature. The following bit-flag values are defined:

Value	Meaning
FKF_AVAILABLE	The FilterKeys features are available.
FKF_CLICKON	The computer makes a click sound when a key is pressed or accepted, that is, if SlowKeys is on, the acceptance is separated from the press and gets a separate click..
FKF_FILTERKEYSON	The FilterKeys features are on.
FKF_HOTKEYACTIVE	The user can turn the FilterKeys feature on and off by holding down the SHIFT key for eight seconds.
FKF_HOTKEYSOUND	If this flag is set, the computer plays a siren sound when the user turns the FilterKeys feature on or off by using the hot key.
iWaitMSec

Specifies the length of time, in milliseconds, that the user must hold down a key before it is accepted by the computer.

iDelayMSec

Specifies the length of time, in milliseconds, that the user must hold down a key before it begins to repeat.

iRepeatMSec

Specifies the length of time, in milliseconds, between each repetition of the keystroke.

iBounceMSec

Specifies the amount of time, in milliseconds, that must elapse after releasing a key before the computer will accept a subsequent press of the same key.

Remarks

Use a FILTERKEYS structure when calling the SystemParametersInfo function with the wAction parameter set to the SPI_GETFILTERKEYS or SPI_SETFILTERKEYS value. When using SPI_GETFILTERKEYS,you must specify the cbSize member of the FILTERKEYS structure; the SystemParametersInfo function fills the remaining members. Specify all structure members when using the SPI_SETFILTERKEYS value.

Either iDelayMSec or iBounceMSec must be zero. They cannot both be non-zero.

See Also

SystemParametersInfo


FIND_NAME_BUFFER

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 the NCBFINDNAME command in the ncb_command member of the NCB structure.

Members

length

Specifies the length, in bytes, of the FIND_NAME_BUFFER structure. Although this structure always occupies 33 bytes, not all of the structure is necessarily valid.

access_control

Specifies the access control for the LAN header.

frame_control

Specifies the frame control for the LAN header.

destination_addr

Specifies the destination address of the remote node where the name was found.

source_addr

Specifies the source address for the remote node where the name was found.

routing_info

Specifies additional routing information.

See Also

FIND_NAME_HEADER, NCB


FIND_NAME_HEADER

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. This structure is followed by as many FIND_NAME_BUFFER structures as are required to describe the name.

Members

node_count

Specifies the number of nodes on which the specified name was found. This structure is followed by the number of FIND_NAME_BUFFER structures specified by the node_count member.

reserved

Reserved.

unique_group

Specifies whether the name is unique. This value is 0 to specify a unique name or 1 to specify a group.

Remarks

The FIND_NAME_HEADER structure is pointed to by the ncb_buffer member of the NCB structure when an application issues an NCBFINDNAME command.

See Also

FIND_NAME_BUFFER, NCB


FINDREPLACE

typedef struct {    // fr

    DWORD        lStructSize;

    HWND         hwndOwner;

    HINSTANCE    hInstance;

    DWORD        Flags;

    LPTSTR        lpstrFindWhat;

    LPTSTR        lpstrReplaceWith;

    WORD         wFindWhatLen;

    WORD         wReplaceWithLen;

    LPARAM        lCustData;

    LPFRHOOKPROC lpfnHook;

    LPCTSTR       lpTemplateName;

} FINDREPLACE;

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 selections in this structure.

Members

lStructSize

Specifies the length, in bytes, of the structure.

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, but it must not be NULL.

hInstance

Identifies a data block that contains a dialog box template specified by the lpTemplateName 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 flags:

Flag	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 specified.
FR_DOWN
	Determines the direction of searches through a document. If this flag is used, the search direction is down; if the flag is not used, 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
	Indicates 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 flag 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 specified 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.

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 member. The hook function should return FALSE to pass a message on to the standard dialog box 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 box, which is done by calling the ShowWindow and UpdateWindow functions. (These calls should be placed after any other paint operations). The following code provides an example:

    // we've returned FALSE in response to WM_INITDIALOG

    // we've performed any other paint operations

    // now we display the dialog box

    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 box will not be shown.

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 resources. This member is used only if the Flags member specifies the FR_ENABLETEMPLATE flag; otherwise, this member is ignored.

See Also

FindText, MAKEINTRESOURCE, ReplaceText, ShowWindow, UpdateWindow, WM_INITDIALOG


FINDTEXT  (preliminaryWindows NT)
FINDTEXT  (preliminary−Windows NT)

typedef struct _findtext {

    CHARRANGE chrg;

    LPSTR lpstrText;

} FINDTEXT;

The FINDTEXT structure contains information about text to search for in a rich edit control. This structure is used with the EM_FINDTEXT message.

Members

chrg

Range to search.

lpstrText

Null-terminated string to find.

See Also

EM_FINDTEXT


FIXED

typedef struct _FIXED { // fix

    WORD  fract;

    short value;

} FIXED;

The FIXED structure contains the integral and fractional parts of a fixed-point real number.

Members

fract

Specifies the fractional part of the number.

value

Specifies the integer part of the number.

Remarks

The FIXED structure is used to describe the elements of the MAT2 structure.

See Also

MAT2


FMS_GETDRIVEINFO

typedef struct _FMS_GETDRIVEINFO { /* fmsgdi */

    DWORD dwTotalSpace;

    DWORD dwFreeSpace;

    TCHAR  szPath[260];

    TCHAR  szVolume[14];

    TCHAR  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).

Members

dwTotalSpace

Specifies the total amount of storage space, in bytes, on the disk associated with the drive.

dwFreeSpace

Specifies the amount of free storage space, in bytes, on the disk associated with the drive.

szPath

Specifies the null-terminated path of the current directory.

szVolume

Specifies the null-terminated volume label of the disk associated with the drive.

szShare

Specifies the null-terminated name of the sharepoint (if the drive is being accessed through a network).

See Also

FMExtensionProc, FM_GETDRIVEINFO


FMS_GETFILESEL

typedef struct _FMS_GETFILESEL { /* fmsgfs */

    FILETIME ftTime;

    DWORD    dwSize;

    BYTE     bAttr;

    TCHAR     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).

Members

ftTime

Specifies the time and date the file was created.

dwSize

Specifies the size, in bytes, of the file.

bAttr

Specifies the attributes of the file.

szName

Specifies the null-terminated full path and filename of the selected file.

See Also

FMExtensionProc


FMS_LOAD

typedef struct _FMS_LOAD { /* fmsld */

    DWORD dwSize;

    TCHAR  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.

Members

dwSize

Specifies the length, in bytes, of the structure.

szMenuName

Specifies the null-terminated name for a menu item that appears on the menu bar in File Manager.

hMenu

Identifies the pop-up menu added to the menu bar in File Manager.

wMenuDelta

Specifies the menu-item delta value. To avoid conflicts with its own menu items, File Manager renumbers the menu-item identifiers in the pop-up menu identified by the hMenu member by adding this delta value to each identifier. An extension DLL that must modify a menu item must identify the item by adding the delta value to the menu item's identifier. The value of this member can vary from session to session.

See Also

FMExtensionProc


FMS_TOOLBARLOAD

typedef struct _FMS_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.

Members

dwSize

Specifies the size, in bytes, of the structure. File Manager sets the size before calling the extension and checks the size after the extension procedure returns.

lpButtons

Points to an array of EXT_BUTTON structures that specify the style, command identifier, and Help string identifier for each toolbar button.

cButtons

Specifies the number of EXT_BUTTON structures in the array pointed to by the lpButtons member. This number equals the number of buttons and separators to add to the toolbar.

cBitmaps

Specifies the number of buttons represented by the given bitmap.

idBitmap

Specifies the identifier of a bitmap resource in the executable file for the extension DLL. The bitmap resource contains images for the number of buttons specified by cBitmaps. File Manager loads the bitmap resource, then uses it to display the buttons.

hBitmap

Specifies the handle of a bitmap that the File Manager will use to obtain and display button images if idBitmap is 0.

See Also

FMEVENT_TOOLBARLOAD, EXT_BUTTON


FOCUS_EVENT_RECORD

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.

Members

bSetFocus

Used internally.

See Also

INPUT_RECORD


FONTSIGNATURE  (preliminaryWindows 95)
FONTSIGNATURE  (preliminary−Windows 95)

typedef struct tagFONTSIGNATURE {
    DWORD  fsUsb[4];
    DWORD  fsCsb[2];
} FONTSIGNATURE;

The FONTSIGNATURE structure contains information identifying the code-pages and Unicode subranges for which a given font provides glyphs.

Members

fsUsb

A 128-bit Unicode subset bitfield (USB) identifying up to 126 Unicode subranges. Each bit, except the two most significant bits, represents a single subrange. The most significant bit is always 1 and identifies the bitfield as a font signature; the second most significant bit is reserved and must be 0. Unicode subranges are numbered in accordance with the ISO 10646 standard.

fsCsb

A 64-bit, code-page bitfield (CPB) that identifies a specific character set or code-page. Windows code-pages are in the lower 32 bits of this bitfield. The high 32 are used for non-Windows code-pages.

Remarks

GDI relies on Windows code-pages fitting within a 32-bit value. Furthermore, the highest two bits within this value are reserved for GDI internal use and may not be assigned to code-pages.


FORM_INFO_1

typedef struct _FORM_INFO_1 { // fi1

    DWORD Flags;

    LPTSTR pName;

    SIZEL  Size;

    RECTL  ImageableArea;

} FORM_INFO_1;

The FORM_INFO_1 structure contains information about a print form. The information includes the print form's origin, its name, its dimensions, and the dimensions of its printable area.

Members

Flags

A set of bit-flags that specify form properties. The following bit-flag is defined:

Value	Meaning
FORM_BUILTIN	If this bit-flag is set, the form is built-in. If this bit-flag is clear, the form is user-defined.
pName

Points to a null-terminated string that specifies the name of the form.

Size

Specifies the width and height, in thousandths of millimeters, of the form.

ImageableArea

Specifies the width and height, in thousandths of millimeters, of the form.

See Also

AddForm, GetForm, SetForm


FORMAT_PARAMETERS

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.

Members

MediaType

Specifies the media type. See MEDIA_TYPE.

StartCylinderNumber

Specifies the cylinder number at which to begin the format.

EndCylinderNumber

Specifies the cylinder number at which to end the format.

StartHeadNumber

Specifies the beginning head location.

EndHeadNumber

Specifies the ending head location.

Remarks

The DeviceIoControl function uses a FORMAT_PARAMETERS structure as input to an IOCTL_DISK_FORMAT_TRACKS device I/O operation.

See Also

DeviceIoControl, IOCTL_DISK_FORMAT_TRACKS, MEDIA_TYPE


FORMATRANGE  (preliminaryWindows NT)
FORMATRANGE  (preliminary−Windows NT)

typedef struct _formatrange {

    HDC hdc;

    HDC hdcTarget;

    RECT rc;

    RECT rcPage;

    CHARRANGE chrg;

} FORMATRANGE;

The FORMATRANGE structure contains information that a rich edit control uses to format its output for a particular device. This structure is used with the EM_FORMATRANGE message.

Members

hdc

Device to render to.

hdcTarget

Target device to format for.

rc

Area to render to.

rcPage

Entire area of rendering device.

chrg

Range of text to format.

See Also

EM_FORMATRANGE


GCP_RESULTS  (preliminaryWindows 95)
GCP_RESULTS  (preliminary−Windows 95)

typedef struct tagGCP_RESULTS {
    DWORD  lStructSize;
    LPTSTR  lpOutString;
    UINT  *lpOrder;
    INT  *lpDx;
    INT  *lpCaretPos;
    LPTSTR lpClass;
    UINT  *lpGlyphs;
    UINT  nGlyphs;
    UINT  nMaxFit;
} GCP_RESULTS;

The GCP_RESULTS structure contains information about characters in a string. This structure receives the results of the GetCharacterPlacement function.

Members

lStructSize

Specifies the size, in bytes, of the structure.

lpOutString

Address of the buffer that receives the output string or is NULL if the output string is not needed. The output string is a version of the original string that is ready to be displayed on a given device. Typically the output string is identical to the original string, but may be different if the string needs reordering and the GCP_REORDER flag is set or if the the original string exceeds the maximum extent and the GCP_MAXEXTENT flag is set.

lpOrder

Address of the array that receives the ordering indices for the characters in the output string or is NULL if the ordering indices are not needed. The original string needs reordering if the GetFontLanguageInfo function returns the GCP_REORDER value.

lpDx

Address of the array that receives the distances between adjacent character cells or is NULL if these distances are not needed. If glyph rendering is done, the distances are for the glyphs not the characters, so the resulting array can be used with the ExtTextOut function.

The distances in this array are in display order. To find the distance for the ith character in the original string, use the lpOrder array as follows:

width = lpDx[lpOrder[i]];

On input, this member must contain justification weight values if the GCP_JUSTIFYIN value is given with the GetCharacterPlacement function.

lpCaretPos

Address of the array that receives the caret position values or is NULL if caret positions are not needed. Each value, except the last, specifies the caret position immediately before the corresponding character. The last value specifies the caret placement for the end of the string. (In some languages the position at the end of the string is not immediately after the string.) If glyph ordering is done, lpCaretPos matches the original string not the output string. This means that some adjacent values may be the same.

The values in this array are in input order. To find the caret position value for the ith character in the original string, use the array as follows:

position = lpCaretPos[i];

lpClass

Address of the array that contains and/or receives character classifications. The values indicate how to lay out characters in the string and are similar (but not identical) to the CT_CTYPE2 values returned by the GetStringTypeEx function. Each element of the array can be set to zero or one of these values:

Value	Meaning
GCPCLASS_ARABIC	Arabic character.
GCPCLASS_HEBREW	Hebrew character.
GCPCLASS_LATIN	Character from a Latin or other single-byte character set for a left-to-right language.
GCPCLASS_LATINNUMBER	Digit from a Latin or other single-byte character set for a left-to-right language.
GCPCLASS_LATINNUMERICSEPARATOR	Input only. Character used to separate Latin digits, such as acomma or decimal point.
GCPCLASS_LATINNUMERICTERMINATOR	Input only. Character used to terminate Latin digits, such as a plus or minus sign.
GCPCLASS_LOCALNUMBER	Digit from the character set associated with the current font.
GCPCLASS_NEUTRAL	Input only. character has no specific classification.
GCPCLASS_NUMERICSEPARATOR	Input only. Character used to separate digits, such as a comma or decimal point.
GCPCLASS_PREBOUNDLTR	For Semitic languages only. Input only. Can combine with other classifications. Set lpClass[0] to GCPCLASS_PREBOUNDLTR to bind the string to left-to-right reading order before the string. Set lpClass[1] to bind the string to the reading order after the string.
CGPCLASS_PREBOUNDRTL	For Semitic languages only. Input only. Can combine with other classifications. Set lpClass[0] to GCPCLASS_PREBOUNDRTL to bind the string to right-to-left reading order before the string. Set lpClass[1] to bind the string to the reading order after the string.
To force the layout of a character to be carried out in a specific way, preset the classification for the corresponding array element; the function leaves such preset classifications unchanged and computes classifications only for array elements that have been set to zero. Preset classifications are used only if the GCP_CLASSIN flag is set and the lpclass array is supplied.

If getFontLanguageInfo does not return GCP_REORDER for the current font, only the GCPCLASS_LATIN value is meaningful.

lpGlyphs

Address of the array that receives the values identifying the glyphs used for rendering the string or is NULL if glyph rendering is not needed. The number of glyphs in the array may be less than the number of characters in the original string if the string contains ligated glyphs. Also if reordering is required, the order of the glyphs may not be sequential.

This array is useful if more than one operation is being done on a string which has any form of ligation, kerning or order-switching. Using the values in this array for subsequent operations saves the time otherwise required to generate the glyph indices each time.

This array always contains glyph indices and the ETO_GLYPH_INDEX value must always be used when this array is used with the ExtTextOut function.

nGlyphs

Number of values in the lpGlyph and lpDx arrays. On input, this member must be set to the size of the arrays pointed to by the lpGlyph and lpDx members. If glyph substitution is not required, (that is, each input character maps to exactly one glyph) this member is the same as the nMaxFit member.

nMaxFit

Number of characters which fit within the extents specified by the nMaxExtent parameter of the GetCharacterPlacement function. This is also the number of elements in the lpOutString, lpOrder, lpCaretPos, and lpClass arrays. If the GCP_MAXEXTENT or GCP_JUSTIFY value is set, this value may be less than the number of characters in the original string. This member is set regardless of whether the GCP_MAXEXTENT or GCP_JUSTIFY values is given.

See Also

ExtTextOut, GetCharacterPlacement, GetFontLanguageInfo


GENERIC_MAPPING

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.

Members

GenericRead

Specifies an access mask defining read access to an object.

GenericWrite

Specifies an access mask defining write access to an object.

GenericExecute

Specifies an access mask defining execute access to an object.

GenericAll

Specifies an access mask defining all possible types of access to an object.

See Also

AccessCheck, AccessCheckAndAuditAlarm, CreatePrivateObjectSecurity, MapGenericMask, SetPrivateObjectSecurity, ACCESS_MASK


GLYPHMETRICS

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.

Members

gmBlackBoxX

Specifies the width of the smallest rectangle that completely encloses the glyph (its "black box").

gmBlackBoxY

Specifies the height of the smallest rectangle that completely encloses the glyph (its "black box").

gmptGlyphOrigin

Specifies the x- and y-coordinates of the upper left corner of the smallest rectangle that completely encloses the glyph.

gmCellIncX

Specifies the horizontal distance from the origin of the current character cell to the origin of the next character cell.

gmCellIncY

Specifies the vertical distance from the origin of the current character cell to the origin of the next character cell.

Remarks

Values in the GLYPHMETRICS structure are specified in device units.

See Also

GetGlyphOutline


HANDLETABLE

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.

Members

objectHandle

Contains an array of handles.

See Also

EnhMetaFileProc, EnumMetaFileProc


HD_HITTESTINFO  (preliminaryWindows NT)
HD_HITTESTINFO  (preliminary−Windows NT)

typedef struct _HD_HITTESTINFO {

    POINT pt;

    UINT flags;

    int iItem;

} HD_HITTESTINFO;

The HD_HITTESTINFO structure contains information about a hit test.

Members

pt

Points to test, in client coordinates

flags

Variable that receives information about the results of a hit test. This member can be one or more of the following values:

Value	Meaning
HHT_NOWHERE	The point is inside the bounding rectangle of the header control but is not over a header item.
HHT_ONDIVIDER	The point is on the divider between two header items.
HHT_ONDIVOPEN	The point is on the divider of an item that has a width of zero. Dragging the divider reveals the item instead of resizing the item to the left of the divider.
HHT_ONHEADER	The point is inside the bounding rectangle of the header control.
HHT_TOLEFT	The point is to the left of the bounding rectangle of the header control.
HHT_TORIGHT	The point is to the right of the bounding rectangle of the header control.
Two of these values can be combined, such as when the position is above and to the left of the client area.

iItem

Receives the index of item at point, if any.

Remarks

This structure is used with the HDM_HITTEST message.

See Also

HDM_HITTEST


HD_ITEM  (preliminaryWindows NT)
HD_ITEM  (preliminary−Windows NT)

typedef struct _HD_ITEM {   hdi

    UINT    mask;

    int     cxy;

    LPTSTR   pszText;

    HBITMAP hbm;

    int     cchTextMax;

    int     fmt;

    LPARAM  lParam;

} HD_ITEM;

The HD_ITEM structure contains information about an item in a header control.

Members

mask

Mask flags that indicate which of the other structure members contain valid data. This member can be a combination of the following values:

Value	Meaning
HDI_BITMAP	The hbm member is valid.
HDI_FORMAT	The fmt member is valid.
HDI_HEIGHT	The cxy member is valid and specifies the height of the item.
HDI_LPARAM	The lParam member is valid.
HDI_TEXT	The pszText and cchTextMax members are valid.
HDI_WIDTH	The cxy member is valid and specifies the width of the item.
cxy

Width or height of item.

pszText

Pointer to item string.

hbm

Handle to item bitmap.

cchTextMax

Length of item string, in characters.

fmt

Format flags. This member can be one of the following values:

Value	Meaning
HDF_CENTER	Centers the contents of the item.
HDF_LEFT	Left aligns the contents of the item.
HDF_RIGHT	Right aligns the contents of the item.
The preceding value is combined with one of the following values:

Value	Meaning
HDF_BITMAP	The item displays a bitmap.
HDF_OWNERDRAW	The owner window of the header control draws the item.
HDF_STRING	The item displays a string.
lParam

Application-defined item data.


HD_LAYOUT  (preliminaryWindows NT)
HD_LAYOUT  (preliminary−Windows NT)

typedef struct _HD_LAYOUT {  // hdl

    RECT FAR* prc;

    WINDOWPOS FAR* pwpos;

} HD_LAYOUT;

The HD_LAYOUT structure contains information used to set the size and position of a header control.

Members

prc

Pointer to a RECT structure that contains the coordinates of a rectangle that the header control is to occupy.

pwpos

Pointer to a WINDOWPOS structure that receives information about the appropriate size and position of the header control.

Remarks

This structure is used with the HDM_LAYOUT message.

See Also

HDM_LAYOUT, RECT, WINDOWPOS


HD_NOTIFY  (preliminaryWindows NT)
HD_NOTIFY  (preliminary−Windows NT)

typedef struct _HD_NOTIFY {  // hdn

    NMHDR   hdr;

    int     iItem;

    int     iButton;

    HD_ITEM FAR* pitem;

} HD_NOTIFY;

The HD_NOTIFY structure contains information used to process notification messages from a header control.

Members

hdr

Required for all WM_NOTIFY messages.z

iItem

Index of item associated with notification.

iButton

Index of the mouse button involved in generating the notification message. This member can be one of these values:

Value	Meaning
0	Left button
1	Right button
2	Middle button
pitem

Pointer to an HD_ITEM structure that contains information about the header item associated with the notification message.

See Also

HD_ITEM, WM_NOTIFY


HELPINFO

typedef  struct  tagHELPINFO {  // hi

    UINT   cbSize;

    int    iContextType

    int    iCtrlId;

    HANDLE hItemHandle;

    DWORD  dwContextId;

    POINT  MousePos;

} HELPINFO, FAR *LPHELPINFO;

The HELPINFO structure contains information about an item for which context-sensitive help has been requested.

cbSize

Specifies the structure size, in bytes.

iContextType

Specifies the type of context for which help is requested. This member can be one of the following values:

Value	Meaning
HELPINFO_MENUITEM	Help requested for a menu item
HELPINFO_WINDOW	Help requested for a control or window
iCtrlId

Specifies the identifier of the window or control if iContextType is HELPINFO_WINDOW. Specifies the identifier of the menu item if iContextType is HELPINFO_MENUITEM.

hItemHandle

Identifies the child window or control if iContextType is HELPINFO_WINDOW. Identifies the associated menu if iContextType is HELPINFO_MENUITEM.

dwContextId

Specifies the help context identifier of the window or control.

MousePos

Specifies a POINT structure that contains the screen coordinates of the mouse cursor. This is useful for providing help based on the position of the mouse cursor.

See Also

POINT


HELPWININFO

typedef struct {    // hwi

    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.

Members

wStructSize

Specifies the structure size, in bytes.

x

Specifies the x-coordinate of the upper-left corner of the window, in screen coordinates.

y

Specifies the y-coordinate of the upper-left corner of the window, in screen coordinates.

dx

Specifies the window width, in pixels.

dy

Specifies the window height, in pixels.

wMax

Specifies how to show the window. This member must be one of the following values:

Value	Action
SW_HIDE	Hides the window and passes activation to another window.
SW_MINIMIZE	Minimizes the specified window and activates the top-level window in the Z order.
SW_RESTORE	Same as SW_SHOWNORMAL.
SW_SHOW	Activates a window and displays it in its current size and position.
SW_SHOWMAXIMIZED	Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED	Activates the window and displays it as an icon.
SW_SHOWMINNOACTIVE	Displays the window as an icon. The window that is currently active remains active.
SW_SHOWNA	Displays the window in its current state. The window that is currently active remains active.
SW_SHOWNOACTIVATE	Displays a window in its most recent size and position. The window that is currently active remains active.
SW_SHOWNORMAL	Activates and displays the window. Whether the window is minimized or maximized, Windows restores it to its original size and position.
rgchMember

Specifies the name of the window.

Remarks

Windows Help divides the display into 1024 units in both the x- and y-directions. To create a secondary window that fills the upper-left quadrant of the display, for example, an application would specify zero for the x and y members and 512 for the dx and dy members.

See Also

WinHelp


HIGHCONTRAST  (preliminaryWindows 95)
HIGHCONTRAST  (preliminary−Windows 95)

typedef struct tagHIGHCONTRAST {     // hc

    UINT cbSize;

    DWORD dwFlags;

    LPTSTR lpszDefaultScheme;

} HIGHCONTRAST, FAR* LPHIGHCONTRAST;

The HIGHCONTRAST structure contains information about the High Contrast Mode accessibility feature, which sets the appearance scheme of the user interface for maximum visibility for a visually-impaired user, and advises applications to comply with this appearance scheme.

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

Specifies a combination of the following values:

Value	Meaning
HCF_AVAILABLE	The High Contrast Mode is available.
HCF_CONFIRMHOTKEY	A confirmation dialog appears when the the High Contrast Mode is activated by using the hot key.
HCF_HIGHCONTRASTON	The High Contrast Mode is on.
HCF_HOTKEYACTIVE	The user can turn the High Contrast Mode on and off by simultaneously pressing the left ALT, left SHIFT, and PRINT SCREEN keys.
HCF_HOTKEYAVAILABLE	The hot key associated with the High Contrast Mode can be enabled. An application can retrieve this value, but cannot set it.
HCF_HOTKEYSOUND	A siren is played when the user turns the High Contrast Mode on or off by using the hot key.
HCF_INDICATOR	A visual indicator is displayed when the High Contrast Mode is on. This value is not currently used and is ignored.
lpszDefaultScheme

Points to a string that contains the name of the default color scheme.

Remarks

An application uses this structure when calling the SystemParametersInfo function with the SPI_GETHIGHCONTRAST or SPI_SETHIGHCONTRAST value. When using SPI_GETHIGHCONTRAST, an application must specify the cbSize member of the HIGHCONTRAST structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SPI_SETHIGHCONTRAST value.

See Also

SystemParametersInfo


HSZPAIR

typedef struct tagHSZPAIR {   // hp

    HSZ hszSvc;

    HSZ hszTopic;

} HSZPAIR;

The HSZPAIR structure contains a DDE service name and topic name. A DDE server application can use this structure during an XTYP_WILDCONNECT transaction to enumerate the service-topic pairs that it supports.

Members

hszSvc

Identifies a service name.

hszTopic

Identifies a topic name.


ICONINFO

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.

Members

fIcon

Specifies whether this structure defines an icon or a cursor. A value of TRUE specifies an icon; FALSE specifies a cursor.

xHotspot

Specifies the x-coordinate of a cursor's hot spot. If this structure defines an icon, the hot spot is always in the center of the icon, and this member is ignored.

yHotspot

Specifies the y-coordinate of the cursor's hot spot. If this structure defines an icon, the hot spot is always in the center of the icon, and this member is ignored.

hbmMask

Specifies the icon bitmask bitmap. If this structure defines a black and white icon, this bitmask is formatted so that the upper half is the icon AND bitmask and the lower half is the icon XOR bitmask. Under this condition, the height should be an even multiple of two. If this structure defines a color icon, this mask only defines the AND bitmask of the icon.

hbmColor

Identifies the icon color bitmap. This member can be optional if this structure defines a black and white icon. The AND bitmask of hbmMask is applied with the SRCAND flag to the destination; subsequently, the color bitmap is applied (using XOR) to the destination by using the SRCINVERT flag.

See Also

CreateIconIndirect, GetIconInfo


ICONMETRICS

typedef struct tagICONMETRICS {

    UINT    cbSize;

    int     iHorzSpacing;

    int     iVertSpacing;

    int     iTitleWrap;

    LOGFONT lfFont;

} ICONMETRICS, FAR *LPICONMETRICS;

The ICONMETRICS structure contains the scalable metrics associated with icons. This structure is used with the SystemParametersInfo function when the SPI_GETICONMETRICS or SPI_SETICONMETRICS action is specified.

Members

cbSize

Specifies the size of the structure, in bytes.

iHorzSpacing and iVertSpacing

Horizontal and vertical space, in pixels, for each arranged icon.

iTitleWrap

Title-wrapping flag. If this member is nonzero, icon titles wrap to a new line. If this member is zero, titles do not wrap.

lfFont

Specifies the font to use for icon titles.

See Also

SystemParametersInfo


IMAGEINFO  (preliminaryWindows NT)
IMAGEINFO  (preliminary−Windows NT)

The IMAGEINFO structure contains information about an image in an image list. This structure is used with the ImageList_GetImageInfo function.

typedef struct _IMAGEINFO {

    HBITMAP hbmImage;  // bitmap containing the images

    HBITMAP hbmMask;   // handle to a monochrome bitmap

    int     Unused1;   // not used

    int     Unused2;   // not used

    RECT    rcImage;   // bounding rectangle of the image

} IMAGEINFO;

Members

hbmMask

Handle to a monochrome bitmap that contains the masks for the images. If the image list does not contain a mask, this member is NULL.

rcImage

Bounding rectangle of the image within the bitmap specified by hbmImage.


INPUT_RECORD

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.

Members

EventType

Identifies the type of input event and the event record stored in the Event member.

This member can have one of the following values:

Value	Meaning
KEY_EVENT
MOUSE_EVENT
WINDOW_BUFFER_SIZE_EVENT
MENU_EVENT
FOCUS_EVENT
Event

Contains a KEY_EVENT_RECORD, MOUSE_EVENT_RECORD, WINDOW_BUFFER_SIZE_RECORD, MENU_EVENT_RECORD, or FOCUS_EVENT_RECORD structure, depending on the event type specified by the EventType member.

See Also

FOCUS_EVENT_RECORD, KEY_EVENT_RECORD, MENU_EVENT_RECORD, MOUSE_EVENT_RECORD, PeekConsoleInput, ReadConsoleInput, WriteConsoleInput


ITEMIDLIST

typedef struct _ITEMIDLIST { // idl

    SHITEMID mkid;  // list of item identifers

} ITEMIDLIST, * LPITEMIDLIST;

typedef const ITEMIDLIST * LPCITEMIDLIST;

Contains a list of item identifiers.


JOB_INFO_1

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.

Members

JobId

Specifies a job identifier.

pPrinterName

Points to a null-terminated string that specifies the name of the printer for which the job is spooled.

pMachineName

Points to a null-terminated string that specifies the name of the machine that created the print job.

pUserName

Points to a null-terminated string that specifies the name of the user that owns the print job.

pDocument

Points to a null-terminated string that specifies the name of the print job (for example, "MS-WORD: Review.doc").

pDatatype

Points to a null-terminated string that specifies the type of data used to record the print job.

pStatus

Points to a null-terminated string that specifies the status of the print job.

Status

Specifies the job status. This member can be one or more of the following values:

JOB_STATUS_DELETING
JOB_STATUS_ERROR
JOB_STATUS_OFFLINE
JOB_STATUS_PAPEROUT
JOB_STATUS_PAUSED
JOB_STATUS_PRINTED
JOB_STATUS_PRINTING
JOB_STATUS_SPOOLING

Priority

Specifies the job priority. This member can be one of the following values or in the range between 1 through 99 (MIN_PRIORITY through MAX_PRIORITY):

Value	Meaning
MIN_PRIORITY	Minimum priority.
MAX_PRIORITY	Maximum priority.
DEF_PRIORITY	Default priority.

Position

Specifies the job's position in the print queue.

TotalPages

Specifies how many pages the document contains.

PagesPrinted

Specifies the number of pages that have printed.

Submitted

Specifies the time that this document was spooled.

See Also

EnumJobs, GetJob, SetJob


JOB_INFO_2

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.

Members

JobId

Specifies a job identifier value.

pPrinterName

Points to a null-terminated string that specifies the name of the printer for which the job is spooled.

pMachineName

Points to a null-terminated string that specifies the name of the machine that created the print job.

pUserName

Points to a null-terminated string that specifies the name of the user who owns the print job.

pDocument

Points to a null-terminated string that specifies the name of the print job (for example, "MS-WORD: Review.doc").

pNotifyName

Points to a null-terminated string that specifies the name of the user who should be notified when the job has been printed or when an error occurs while printing the job.

pDatatype

Points to a null-terminated string that specifies the type of data used to record the print job.

pPrintProcessor

Points to a null-terminated string that specifies the name of the print processor that should be used to print the job.

pParameters

Points to a null-terminated string that specifies print-processor parameters.

pDriverName

Points to a null-terminated string that specifies the name of the printer driver that should be used to process the print job.

pDevMode

Points to a DEVMODE structure that contains device-initialization and environment data for the printer driver.

pStatus

Points to a null-terminated string that specifies the status of the print job.

pSecurityDescriptor

The value of this member is NULL. Retrieval and setting of document security descriptors is not supported in this release.

Status

Specifies the job status. This member can be one or more of the following values:

JOB_STATUS_PAUSED
JOB_STATUS_ERROR
JOB_STATUS_DELETING
JOB_STATUS_SPOOLING
JOB_STATUS_PRINTING
JOB_STATUS_OFFLINE
JOB_STATUS_PAPEROUT
JOB_STATUS_PRINTED

Priority

Specifies the job priority. This member can be one of the following values or in the range between 1 through 99 (MIN_PRIORITY through MAX_PRIORITY):

Value	Meaning
MIN_PRIORITY	Minimum priority.
MAX_PRIORITY	Maximum priority.
DEF_PRIORITY	Default priority.
Position

Specifies the job's position in the print queue.

StartTime

Specifies the earliest time that the job can be printed.

UntilTime

Specifies the the latest time that the job can be printed.

TotalPages

Specifies the number of pages required for the job.

Size

Specifies the size, in bytes, of the job.

Submitted

Specifies the time when the job was submitted.

Time

Specifies the total time, in seconds, that has elapsed since the job began printing.

PagesPrinted

Specifies the number of pages that have printed.

See Also

DEVMODE, EnumJobs, GetJob, SetJob


KERNINGPAIR

typedef struct tagKERNINGPAIR { // kp

    WORD wFirst;

    WORD wSecond;

    int  iKernAmount;

} KERNINGPAIR;

The KERNINGPAIR structure defines a kerning pair.

Members

wFirst

Specifies the character code for the first character in the kerning pair.

wSecond

Specifies the character code for the second character in the kerning pair.

iKernAmount

Specifies the amount this pair will be kerned if they appear side by side in the same font and size. This value is typically negative, because pair kerning usually results in two characters being set more tightly than normal. The value is given in logical units — that is, it depends on the current mapping mode.

See Also

GetKerningPairs


KEY_EVENT_RECORD

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.

Members

bKeyDown

Specifies TRUE if the key is being pressed, FALSE if the key is being released.

wRepeatCount

Specifies a count indicating that a key is being held down. For example, when a key is held down, you might get five events with this member equal to 1, one event with this member equal to 5, or multiple events with this member greater than or equal to 1.

wVirtualKeyCode

Specifies the virtual-key code that identifies the given key in a device-independent manner.

wVirtualScanCode

Specifies the virtual scan code of the given key that represents the device-dependent value generated by the keyboard hardware.

uChar

Specifies the translated Unicode or ASCII character, depending on whether the wide-character (Unicode) or ANSI version of the ReadConsoleInput function was used.

dwControlKeyState

Indicates the state of the control keys. This member can be a combination of the following values:

Value	Meaning
CAPSLOCK_ON	The CAPS LOCK light is on.
ENHANCED_KEY	The key is enhanced.
LEFT_ALT_PRESSED	The left ALT key is pressed.
LEFT_CTRL_PRESSED	The left CTRL key is pressed.
NUMLOCK_ON	The NUM LOCK light is on.
RIGHT_ALT_PRESSED	The right ALT key is pressed.
RIGHT_CTRL_PRESSED	The right CTRL key is pressed.
SCROLLLOCK_ON	The SCROLL LOCK light is on.
SHIFT_PRESSED	The SHIFT key is pressed.
Remarks

Enhanced keys for the IBM® 101- and 102-key keyboards are the INS, DEL, HOME, END, PAGE UP, PAGE DOWN, and direction keys in the clusters to the left of the keypad; and the divide (/) and ENTER keys in the keypad.

Keyboard input events are generated when any key, including control keys, is pressed or released. However, the ALT key when pressed and released without combining with another character, has special meaning to Windows and is not passed through to the application. Also, the CTRL+C key combination is not passed through if the input handle is in processed mode (ENABLE_PROCESSED_INPUT).

See Also

PeekConsoleInput, ReadConsoleInput, WriteConsoleInput, INPUT_RECORD


LANA_ENUM

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.

Members

length

Specifies the number of valid entries in the array of LAN adapter numbers.

lana

Specifies an array of LAN adapter numbers.

Remarks

The LANA_ENUM structure is pointed to by the ncb_buffer member of the NCB structure when an application issues the NCBENUM command. The NCBENUM command is not part of the IBM NetBIOS 3.0 specification.

See Also

NCB


LARGE_INTEGER

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.

Members

LowPart

Specifies the low-order 32 bits.

HighPart

Specifies the high-order 32 bits.

See Also

LUID, ULARGE_INTEGER


LDT_ENTRY

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.

Members

LimitLow

Contains the low 16 bits of the address of the last byte in the segment.

BaseLow

Contains the low 16 bits of the base address of the segment.

HighWord

Contains the high two words of the descriptor. This member may be interpreted as bytes or collections of bits, depending on the level of detail required.

The members of the Bits structure are as follows:

Member	Contents
BaseMid	Middle bits (16−23) of the base address of the segment.
Type	Bitmask that indicates the type of segment. This member can be one of the following values:
Value	Meaning
0	Read-only data segment
1	Read-write data segment
2	Unused segment
3	Read-write expand-down data segment
4	Execute-only code segment
5	Executable-readable code segment
6	Execute-only "conforming" code segment
7	Executable-readable "conforming" code segment
Dpl	Privilege level of the descriptor. This member is an integer value in the range 0 (most privileged) through 3 (least privileged).
Pres	Present flag. This member is 1 if the segment is present in physical memory or 0 if it is not.
LimitHi	High bits (16−19) of the address of the last byte in the segment.
Sys	Space that is available to system programmers. This member might be used for marking segments in some system-specific way.
Reserved_0	Reserved.
Default_Big	Size of segment. If the segment is a data segment, this member contains 1 if the segment is larger than 64 kilobytes (K) or 0 if the segment is smaller than or equal to 64K.
	If the segment is a code segment, this member contains 1 if the segment is a code segment and runs with the default (native mode) instruction set. This member contains 0 if the code segment is an 80286 code segment and runs with 16-bit offsets and the 80286-compatible instruction set.
Granularity	Granularity. This member contains 0 if the segment is byte granular, 1 if the segment is page granular.
BaseHi	High bits (24−31) of the base address of the segment.
The members of the Bytes structure are as follows:

Member	Contents
BaseMid	Middle bits (16−23) of the base address of the segment.
Flags1	Values of the Type, Dpl, and Pres members in the Bits structure.
Flags2	Values of the LimitHi, Sys, Reserved_0, Default_Big, and Granularity members in the Bits structure.
BaseHi	High bits (24−31) of the base address of the segment.
Remarks

The GetThreadSelectorEntry function fills this structure with information from an entry in the descriptor table. You can use this information to convert a segment-relative address to a linear virtual address.

The base address of a segment is the address of offset 0 in the segment. To calculate this value, combine the BaseLow, BaseMid, and BaseHi members.

The limit of a segment is the address of the last byte that can be addressed in the segment. To calculate this value, combine the LimitLow and LimitHi members.

See Also

GetThreadSelectorEntry


LIST_ENTRY

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.

Members

Flink

Points to the preceding entry in a double-linked list.

Blink

Points to the next entry in a double-linked list.

Remarks

This structure can be used as the beginning of a double-linked list or as any subsequent entry in the list.


LOAD_DLL_DEBUG_INFO

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.

Members

hFile

Identifies a handle of the DLL. If this member is NULL, the handle is not valid. Otherwise, the member is opened for reading and read-sharing in the context of the debugger.

lpBaseOfDll

Points to the base address of the DLL in the address space of the process loading the DLL.

dwDebugInfoFileOffset

Specifies the offset to the debugging information in the file identified by the hFile member. The kernel expects the debugging information to be in CodeView 4.0 format. This format is currently a derivative of Common Object File Format (COFF).

nDebugInfoSize

Specifies the size, in bytes, of the debugging information in the file. If this value is zero, there is no debugging information.

lpImageName

Points to the filename associated with hFile. This member may be NULL, or it may contain the address of a string pointer in the address space of the process being debugged. That address may, in turn, either be NULL or point to the actual filename. If fUnicode is a nonzero value, the name string is Unicode; otherwise, it is ANSI.

This member is strictly optional. Debuggers must be prepared to handle the case where lpImageName is NULL or *lpImageName (in the address space of the process being debugged) is NULL. Specifically, this release of Windows NT will never provide an image name for a create process event, and it will not likely pass an image name for the first DLL event. This version of Windows NT will also never provide this information in the case of debugging events that originate from a call to the DebugActiveProcess function.

fUnicode

Indicates whether a filename specified by lpImageName is Unicode or ANSI. A nonzero value for this member indicates Unicode; zero indicates ANSI.

See Also

CREATE_PROCESS_DEBUG_INFO, CREATE_THREAD_DEBUG_INFO, DebugActiveProcess, DEBUG_EVENT


LOCALESIGNATURE  (preliminaryWindows 95)
LOCALESIGNATURE  (preliminary−Windows 95)

typedef struct tagLOCALESIGNATURE {
    DWORD  lsUsb[4];
    DWORD  lsCsbDefault[2];
    DWORD  lsCsbSupported[2];
} LOCALESIGNATURE;

The LOCALESIGNATURE structure contains extended font-signature information, including two code-page bitfields (CPBs) that define the default and supported character sets and code-pages. This structure is typically used to represent the relationships between font coverage and locales.

Members

lsUsb

A 128-bit Unicode subset bitfield (USB) identifying up to 126 Unicode subranges. Each bit, except the two most significant bits, represents a single subrange. The most significant bit is always 1 and identifies the bitfield as a font signature; the second most significant is reserved and must be 0. Unicode subranges are numbered in accordance with the ISO 10646 standard.

lsCsbDefault

A code-page bitfield that indicates the default OEM and ANSI code-pages for a locale. The code-pages may be identified by separate bits or a single bit representing a common ANSI and OEM code-page.

lsCsbSupported

A code-page bitfield that indicates all the code-pages in which the locale can be supported.


LOGBRUSH

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.

Members

lbStyle

Specifies the brush style. The lbStyle member must be one of the following styles:

Value	Meaning
BS_DIBPATTERN	A pattern brush defined by a device-independent bitmap (DIB) specification. If lbStyle is BS_DIBPATTERN, the lbHatch member contains a handle to a packed DIB.
BS_DIBPATTERN8X8	Same as BS_DIBPATTERN.
BS_DIBPATTERNPT	A pattern brush defined by a device-independent bitmap (DIB) specification. If lbStyle is BS_DIBPATTERNPT, the lbHatch member contains a pointer to a packed DIB.
BS_HATCHED	Hatched brush.
BS_HOLLOW	Hollow brush.
BS_NULL	Same as BS_HOLLOW.
BS_PATTERN	Pattern brush defined by a memory bitmap.
BS_PATTERN8X8	Same as BS_PATTERN.
BS_SOLID	Solid brush.
lbColor

Specifies the color in which the brush is to be drawn. If lbStyle is the BS_HOLLOW or BS_PATTERN style, lbColor is ignored.

If lbStyle is BS_DIBPATTERN or BS_DIBPATTERNBT, the low-order word of lbColor specifies whether the bmiColors members of the BITMAPINFO structure contain explicit red, green, blue (RGB) values or indices into the currently realized logical palette. The lbColor member must be one of the following values:

Value	Meaning
DIB_PAL_COLORS	The color table consists of an array of 16-bit indices into the currently realized logical palette.
DIB_RGB_COLORS	The color table contains literal RGB values.
lbHatch

Specifies a hatch style. The meaning depends on the brush style defined by lbStyle.

If lbStyle is BS_DIBPATTERN, the lbHatch member contains a handle to a packed DIB. If lbStyle is BS_DIBPATTERNPT, the lbHatch member contains a pointer to a packed DIB.

If lbStyle is BS_HATCHED, the lbHatch member specifies the orientation of the lines used to create the hatch. It can be one of the following values:

Value	Meaning
HS_BDIAGONAL	A 45-degree upward, left-to-right hatch
HS_CROSS	Horizontal and vertical cross-hatch
HS_DIAGCROSS	45-degree crosshatch
HS_FDIAGONAL	A 45-degree downward, left-to-right hatch
HS_HORIZONTAL	Horizontal hatch
HS_VERTICAL	Vertical hatch
If lbStyle is BS_PATTERN, lbHatch is a handle to the bitmap that defines the pattern. The bitmap cannot be a DIB section bitmap, which is created by the CreateDIBSection function.

If lbStyle is BS_SOLID or BS_HOLLOW, lbHatch is ignored.

Remarks

Although lbColor controls the foreground color of a hatch brush, the SetBkMode and SetBkColor functions control the background color.

See Also

BITMAPINFO, CreateBrushIndirect, CreateDIBSection, ExtCreatePen, SetBkColor, SetBkMode


LOGCOLORSPACE  (preliminaryWindows 95)
LOGCOLORSPACE  (preliminary−Windows 95)

typedef long FXPT16DOT16, FAR* LPFXPT16DOT16;  // fixed point 16.16
typedef LONG LCSCSTYPE
typedef LONG LCSGAMUTMATCH

typedef struct tagLOGCOLORSPACE {
    DWORD         lcsSignature;

    DWORD         lcsVersion;

    DWORD         lcsSize;

    LCSCSTYPE     lcsCSType;

    LCSGAMUTMATCH lcsIntent;

    CIEXYZTRIPLE  lcsEndpoints;
    DWORD         lcsGammaRed;
    DWORD         lcsGammaGreen;

    DWORD         lcsGammaBlue;
    TCHAR         lcsFilename[MAX_PATH];

} LOGCOLORSPACE, *LPLOGCOLORSPACE;

The LOGCOLORSPACE structure contains information that defines a logical color space.

Members

lcsSignature

Color space signature.

lcsVersion

Version number; must be 0x400.

lcsSize

Size of this structure, in bytes.

lcsCSType

Color space type. Can be one of the following values:

Value	Meaning
LCS_DEVICE_RGB	Color values are device RGB values. The values are passed to the device without translation.
LCS_DEVICE_CMYK	Color values are device CMYK values. The values are passed to the device without translation
LCS_CALIBRATED_RGB	Color values are calibrated RGB values. The values are translated using the endpoints specified by the lcsEndpoints member before being passed to the device.
If LCS_CALIBRATED_RGB is not specified, the lcsEndpoints member is ignored.

lcsIntent

The gamut matching method. Can be one of the following values:

Value	Meaning
LCS_GM_BUSINESS	Maintain saturation. Used for business charts and other situations in which undithered colors are required.
LCS_GM_GRAPHICS	Maintain colormetric match. Used for graphic designs and named colors.
LCS_GM_IMAGES	Maintain contrast. Used for photographs and natural images.
lcsEndpoints

Red, green, blue endpoints.

lcsGammaRed

Scale of the red coordinate.

lcsGammaGreen

Scale of the green coordinate.

lcsGammaBlue

Scale of the blue coordinate.

lcsFilename

A null-terminated string that names a color profile file. This member is typically set to zero, but may be used to set the color space to be exactly as specified by the color profile. This is useful for devices that input color values for a specific printer, or when using an installable image color matcher. If a color profile is specified, all other members of this structure should be set to reasonable values, even if the values are not 100 percent accurate.

See Also

RGB, CMYK


LOGFONT

typedef struct tagLOGFONT { // lf

   LONG lfHeight;

   LONG lfWidth;

   LONG lfEscapement;

   LONG lfOrientation;

   LONG lfWeight;

   BYTE lfItalic;

   BYTE lfUnderline;

   BYTE lfStrikeOut;

   BYTE lfCharSet;

   BYTE lfOutPrecision;

   BYTE lfClipPrecision;

   BYTE lfQuality;

   BYTE lfPitchAndFamily;

   TCHAR lfFaceName[LF_FACESIZE];

} LOGFONT;

The LOGFONT structure defines the attributes of a font.

Members

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 the graphics device interface (GDI) must attempt to match the logical-font attributes to those of an actual physical font. It can be one of the following values:

Value	Meaning
DEFAULT_QUALITY	Appearance of the font does not matter.
DRAFT_QUALITY	Appearance of the font is less important than when PROOF_QUALITY is used. For GDI 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 (monospace), with or without serifs. Monospace fonts are usually modern. Pica, Elite, and CourierNew® are examples.
FF_ROMAN	Fonts with variable stroke width (proportional) and with serifs. MS® Serif is an example.
FF_SCRIPT	Fonts designed to look like handwriting. Script and Cursive are examples.
FF_SWISS	Fonts with variable stroke width (proportional) and without serifs. MS® Sans Serif is an example.
lfFaceName

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 EnumFontFamilies 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, EnumFontFamilies


LOGPALETTE

typedef struct tagLOGPALETTE { // lgpl

    WORD         palVersion;

    WORD         palNumEntries;

    PALETTEENTRY palPalEntry[1];

} LOGPALETTE;

The LOGPALETTE structure defines a logical color palette.

Members

palVersion

Specifies the Windows version number for the structure (currently 0x300).

palNumEntries

Specifies the number of entries in the logical color palette.

palPalEntry

Specifies an array of PALETTEENTRY structures that define the color and usage of each entry in the logical palette.

Remarks

The colors in the palette-entry table should appear in order of importance because entries earlier in the logical palette are most likely to be placed in the system palette.

See Also

CreatePalette, PALETTEENTRY


LOGPEN

typedef struct tagLOGPEN { // lgpn

    UINT     lopnStyle;

    POINT    lopnWidth;

    COLORREF lopnColor;

} LOGPEN;

The LOGPEN structure defines the style, width, and color of a pen. The CreatePenIndirect function uses the LOGPEN structure.

Members

lopnStyle

Specifies the pen style, which can be one of the following values:

Value	Meaning
PS_SOLID	Pen is solid.
PS_DASH	Pen is dashed.
PS_DOT	Pen is dotted.
PS_DASHDOT	Pen has alternating dashes and dots.
PS_DASHDOTDOT	Pen has dashes and double dots.
PS_NULL	Pen is invisible.
PS_INSIDEFRAME	Pen is solid. When this pen is used in any graphics device interface (GDI) drawing function that takes a bounding rectangle, the dimensions of the figure are shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen. This applies only to geometric pens.
lopnWidth

Specifies the POINT structure that contains the pen width, in logical units. If the pointer member is NULL, the pen is one pixel wide on raster devices. The y member in the POINT structure for lopnWidth is not used.

lopnColor

Specifies the pen color.

Remarks

If the width of the pen is greater than 1 and the pen style is PS_INSIDEFRAME, the line is drawn inside the frame of all GDI objects except polygons and polylines. If the pen color does not match an available red, green, blue (RGB) value, the pen is drawn with a logical (dithered) color. If the pen width is less than or equal to 1, the PS_INSIDEFRAME style is identical to the PS_SOLID style.

See Also

CreatePenIndirect, POINT, RGB


LUID

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

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.

Members

Luid

Specifies an LUID value.

Attributes

Specifies attributes of the LUID. This value contains up to 32 one-bit flags. Its meaning is dependent on the definition and use of the LUID.

Remarks

An LUID_AND_ATTRIBUTES structure can represent an LUID whose attributes change frequently, such as when it is used to represent privileges in the PRIVILEGE_SET structure. Privileges are represented by LUIDs and have attributes indicating whether they are currently enabled or disabled.

See Also

AllocateLocallyUniqueId, LUID, PRIVILEGE_SET, TOKEN_PRIVILEGES


LV_COLUMN  (preliminaryWindows NT)
LV_COLUMN  (preliminary−Windows NT)

typedef struct _LV_COLUMN {

    UINT mask;

    int fmt;

    int cx;

    LPTSTR pszText;

    int cchTextMax;

    int iSubItem;

} LV_COLUMN;

The LV_COLUMN structure contains information about a column in report view. This structure is also used to receive information about a column.

Members

mask

Variable specifying which members contain valid information. This member can be LVCF_ALL (meaning all members), zero, or one or more of the following values:

Value	Meaning
LVCF_FMT	The fmt member is valid.
LVCF_SUBITEM	The iSubItem member is valid.
LVCF_TEXT	The pszText member is valid.
LVCF_WIDTH	The cx member is valid.
fmt

Alignment of the column. This member can be one of the following values: LVCFMT_LEFT, LVCFMT_RIGHT, or LVCFMT_CENTER.

cx

Width of the column, in pixels.

pszText

Pointer to a null-terminated string that contains the column heading if the structure contains information about a column. If the structure is receiving information about a column, this member specifies the address of the buffer that receives the column heading.

cchTextMax

Size of the buffer pointed to by the pszText member. If the structure is not receiving information about a column, this member is ignored.

iSubItem

Index of subitem associated with column.

Remarks

This structure is used with the LVM_GETCOLUMN, LVM_SETCOLUMN, LVM_INSERTCOLUMN, and LVM_DELETECOLUMN messages.

See Also

LVM_DELETECOLUMN, LVM_GETCOLUMN, LVM_INSERTCOLUMN, LVM_SETCOLUMN


LV_DISPINFO  (preliminaryWindows NT)
LV_DISPINFO  (preliminary−Windows NT)

typedef struct tagLV_DISPINFO {

    NMHDR   hdr;

    LV_ITEM item;

} LV_DISPINFO;

The LV_DISPINFO structure contains information needed to display an owner-drawn item in a list view control. The LV_DISPINFO structure is used with the LVN_GETDISPINFO and LVN_SETDISPINFO notification messages.

Members

hdr

Required for all WM_NOTIFY messages.

item

LV_ITEM structure that identifies the item or subitem. The structure either contains or receives information about the item. The mask member contains a set of bit flags that specify which item attributes are relevant. You can set one or more of the following bit flags:

Value	Meaning
LVIF_IMAGE	The iImage member specifies, or is to receive, the index of the item's icon in the image list.
LVIF_STATE	The state member specifies, or is to receive, the state of the item.
LVIF_TEXT	The pszText member specifies the new item text or the address of a buffer that is to receive the item text.
If the structure is receiving item text, the pszText and cchTextMax members specify the address and size of a buffer. You can either copy text to the buffer or assign the address of a string to the pszText member. In the latter case, you must not change or delete the string until the corresponding item text is deleted or two additional LVN_GETDISPINFO messages have been sent.

If you are handling the LVN_GETDISPINFO message, you can set the LVIF_DI_SETITEM flag in the mask member. This tells the operating system to store the requested list item information, and not ask for it again.

See Also

LV_ITEM, LVN_GETDISPINFO, LVN_SETDISPINFO, WM_NOTIFY


LV_FINDINFO  (preliminaryWindows NT)
LV_FINDINFO  (preliminary−Windows NT)

typedef struct _LV_FINDINFO {

    UINT flags;

    LPCTSTR psz;

    LPARAM lParam;

    POINT pt;

    UINT vkDirection;

} LV_FINDINFO;

The LV_FINDINFO structure contains information used to search for a list view item.

Members

flags

Type of search to perform. This member can be one or more of the following values:

Value	Meaning
LVFI_PARAM	Searches based on the lParam member. The lParam member of the matching item's LV_ITEM structure must match the lParam member of this structure. If this value is specified, all other values are ignored.
LVFI_PARTIAL	Matches if the item text begins with the string pointed to by the psz member. This value implies use of LVFI_STRING.
LVFI_STRING	Searches based on the item text. Unless additional values are specified, the item text of the matching item must exactly match the string pointed to by the psz member.
LVFI_WRAP	Continues the search at the beginning if no match is found.
LVFI_NEARESTXY	Finds the item nearest the specified position in the specified direction.
psz

Pointer to a null-terminated string to compare with the item text if flags specifies LVFI_STRING or LVFI_PARTIAL.

lParam

Value to compare with the lParam member of a list view item's LV_ITEM structure if the flags member specifies LVFI_PARAM.

pt

POINT structure that specifies the starting position to search from. This member is used only if LVFI_NEARESTXY is specified.

vkDirection

Direction to search in. This member is used only if LVFI_NEARESTXY is specified. If this member used, it specifies the virtual-key code of an arrow key.

Remarks

The LV_FINDINFO structure is used with the LVM_FINDITEM message.

See Also

LV_ITEM, LVM_FINDITEM, POINT


LV_HITTESTINFO  (preliminaryWindows NT)
LV_HITTESTINFO  (preliminary−Windows NT)

typedef struct _LV_HITTESTINFO {

    POINT pt;

    UINT flags;

    int iItem;

} LV_HITTESTINFO;

The LV_HITTESTINFO structure contains information about a hit test.

Members

pt

Position to hit test, in client coordinates.

flags

Variable that receives information about the results of a hit test. This member can be one or more of the following values:

Value	Meaning
LVHT_ABOVE	The position is above the client area of the control.
LVHT_BELOW	The position is below the client area of the control.
LVHT_NOWHERE	The position is inside the list view control's client window, but it is not over a list item.
LVHT_ONITEMICON	The position is over a list view item's icon.
LVHT_ONITEMLABEL	The position is over a list view item's text.
LVHT_ONITEMSTATEICON	The position is over the state image of a list view item.
LVHT_TOLEFT	The position is to the left of the list view control's client area.
LVHT_TORIGHT	The position is to the right of the list view control's client area.
You can use LVHT_ABOVE, LVHT_BELOW, LVHT_TOLEFT, and LVHT_TORIGHT to determine whether to scroll the contents of a list view control. Two of these values may be combined — for example, if the position is above and to the left of the client area.

You can test for LVHT_ONITEM to determine whether a specified position is over a list view item. This value is a bitwise-OR operation on LVHT_ONITEMICON, LVHT_ONITEMLABEL, and LVHT_ONITEMSTATEICON.

iItem

Receives the index of the matching item.

Remarks

This structure is used with the LVM_HITTEST message.

See Also

LVM_HITTEST


LV_ITEM  (preliminaryWindows NT)
LV_ITEM  (preliminary−Windows NT)

typedef struct _LV_ITEM {

    UINT   mask;

    int    iItem;

    int    iSubItem;

    UINT   state;

    UINT   stateMask;

    LPTSTR  pszText;

    int    cchTextMax;

    int    iImage;       // index of the list view item's icon

    LPARAM lParam;       // 32-bit value to associate with item

} LV_ITEM;

The LV_ITEM structure specifies or receives the attributes of a list view item.

Members

mask

A set of bit flags that specify attributes of this data structure or of an operation that is using this structure.

The following bit flags specify the members of the LV_ITEM structure that contain valid data or need to be filled in. One or more of these bit flags may be set:

Value	Meaning
LVIF_TEXT	The pszText member is valid or needs to be filled in.
LVIF_IMAGE	The iImage member is valid or needs to be filled in.
LVIF_PARAM	The lParam member is valid or needs to be filled in.
LVIF_STATE	The state member is valid or needs to be filled in..
The following bit flag is used with the LVN_GETDISPINFO notification message:

Value	Meaning
LVIF_DI_SETITEM	The operating system should store the requested list item information, and not ask for it again.
iItem

Item that this structure refers to.

iSubItem

Subitem that this structure refers to, or zero.

state and statemask

Current state of the item, and the valid states of the item. This member can be any valid combination of state flags.

pszText

Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the item is a callback item.

If the structure is receiving item attributes, this member is the pointer to the buffer that receives the item text.

cchTextMax

Size of the buffer pointed to by the pszText member if the structure is receiving item attributes. If the structure specifies item attributes, this member is ignored.

iImage

Index of the list view item's icon in the icon and small icon image lists. If this member is the I_IMAGECALLBACK value, the item is a callback item.

Remarks

The LV_ITEM structure is used with a number of messages, including LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM, and LVM_DELETEITEM.

See Also

LVM_DELETEITEM, LVM_GETITEM, LVM_INSERTITEM, LVM_SETITEM


LV_KEYDOWN  (preliminaryWindows NT)
LV_KEYDOWN  (preliminary−Windows NT)

typedef struct tagLV_KEYDOWN {

    NMHDR hdr;

    WORD wVKey;

    UINT flags;

} LV_KEYDOWN;

The LV_KEYDOWN structure contains information about a keyboard event in a list view control.

Members

hdr

Required for all WM_NOTIFY messages.

wVKey

Virtual-key code.

flags

Always zero.

Remarks

The LV_KEYDOWN structure is used with the LVN_KEYDOWN notification message.

See Also

LVN_KEYDOWN, WM_NOTIFY


MAT2

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.

Members

eM11

Specifies a fixed-point value for the M11 component of a 3 by 3 transformation matrix.

eM12

Specifies a fixed-point value for the M12 component of a 3 by 3 transformation matrix.

eM21

Specifies a fixed-point value for the M21 component of a 3 by 3 transformation matrix.

eM22

Specifies a fixed-point value for the M22 component of a 3 by 3 transformation matrix.

Remarks

The identity matrix produces a transformation in which the transformed graphical object is identical to the source object. In the identity matrix, the value of eM11 is 1, the value of eM12 is zero, the value of eM21 is zero, and the value of eM22 is 1.

See Also

GetGlyphOutline


MDICREATESTRUCT

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.

Members

szClass

Points to a null-terminated string specifying the name of the window class of the MDI child window. The class name must have been registered by a previous call to the RegisterClass function.

szTitle

Points to a null-terminated string that represents the title of the MDI child window. Windows displays the title in the child window's title bar.

hOwner

Identifies the instance of the application creating the MDI client window.

x

Specifies the initial horizontal position, in client coordinates, of the MDI child window. If this member is CW_USEDEFAULT, the MDI child window is assigned the default horizontal position.

y

Specifies the initial vertical position, in client coordinates, of the MDI child window. If this member is CW_USEDEFAULT, the MDI child window is assigned the default vertical position.

cx

Specifies the initial width, in device units, of the MDI child window. If this member is CW_USEDEFAULT, the MDI child window is assigned the default width.

cy

Specifies the initial height, in device units, of the MDI child window. If this member is set to CW_USEDEFAULT, the MDI child window is assigned the default height.

style

Specifies the style of the MDI child window. If the MDI client window was created with the MDIS_ALLCHILDSTYLES window style, this member can be any combination of the window styles listed in the description of the CreateWindow function. Otherwise, this member can be one or more of the following values:

Value	Meaning
WS_MINIMIZE	Creates an MDI child window that is initially minimized.
WS_MAXIMIZE	Creates an MDI child window that is initially maximized.
WS_HSCROLL	Creates an MDI child window that has a horizontal scroll bar.
WS_VSCROLL	Creates an MDI child window that has a vertical scroll bar.
lParam

Specifies an application-defined 32-bit value.

Remarks

When the MDI child window is created, Windows sends the WM_CREATE message to the window. The lParam parameter of WM_CREATE contains a pointer to a CREATESTRUCT structure. The lpCreateParams member of this structure contains a pointer to the MDICREATESTRUCT structure passed with the WM_MDICREATE message that created the MDI child window.

See Also

CLIENTCREATESTRUCT, CREATESTRUCT, WM_CREATE


MEASUREITEMSTRUCT

typedef struct tagMEASUREITEMSTRUCT {   // mis

    UINT  CtlType;      // type of control

    UINT  CtlID;        // combo box, list box, or button identifier

    UINT  itemID;       // menu item, variable-height list box, or combo box identifier

    UINT  itemWidth;    // width of menu item, in pixels

    UINT  itemHeight;   // height of single item in list box menu, in pixels

    DWORD itemData;     // application-defined 32-bit value

} MEASUREITEMSTRUCT;

The MEASUREITEMSTRUCT structure informs Windows of the dimensions of an owner-drawn control or menu item. This allows Windows to process user interaction with the control correctly.

Members

CtlType

Specifies the control type. This member can be one of the following values:

Value	Meaning
ODT_BUTTON	Owner-drawn button
ODT_COMBOBOX	Owner-drawn combo box
ODT_LISTBOX	Owner-drawn list box
ODT_MENU	Owner-drawn menu
CtlID

Specifies the identifier of the combo box, list box, or button. This member is not used for a menu.

itemID

Specifies the identifier for a menu item or the position of a list box or combo box item. This value is specified for a list box only if it has the LBS_OWNERDRAWVARIABLE style; this value is specified for a combo box only if it has the CBS_OWNERDRAWVARIABLE style.

itemWidth

Specifies the width, in pixels, of a menu item. Before returning from the message, the owner of the owner-drawn menu item must fill this member.

itemHeight

Specifies the height, in pixels, of an individual item in a list box or a menu. Before returning from the message, the owner of the owner-drawn combo box, list box, or menu item must fill out this member.

itemData

Specifies the application-defined 32-bit value associated with the menu item. For a control, this member specifies the value last assigned to the list box or combo box by the LB_SETITEMDATA or CB_SETITEMDATA message. If the list box or combo box has the LB_HASSTRINGS or CB_HASSTRINGS style, this value is initially zero. Otherwise, this value is initially the value passed to the list box or combo box in the lParam parameter of one of the following messages:

CB_ADDSTRING
CB_INSERTSTRING
LB_ADDSTRING
LB_INSERTSTRING

Remarks

The owner window of an owner-drawn control receives a pointer to the MEASUREITEMSTRUCT structure as the lParam parameter of a WM_MEASUREITEM message. The owner-drawn control sends this message to its owner window when the control is created. The owner then fills in the appropriate members in the structure for the control and returns. This structure is common to all owner-drawn controls.

If an application does not fill the appropriate members of MEASUREITEMSTRUCT, the control or menu item may not be drawn properly.

See Also

CB_ADDSTRING, CB_INSERTSTRING, CB_SETITEMDATA, LB_ADDSTRING, LB_INSERTSTRING, LB_SETITEMDATA, WM_MEASUREITEM


MEMORY_BASIC_INFORMATION

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 virtual address space of a process. The VirtualQuery and VirtualQueryEx functions use this structure.

Members

BaseAddress

Points to the base address of the region of pages.

AllocationBase

Points to the base address of a range of pages allocated by the VirtualAlloc function. The page pointed to by the BaseAddress member is contained within this allocation range.

AllocationProtect

Specifies the access protection given when the region was initially allocated. One of the following flags can be present, along with the PAGE_GUARD and PAGE_NOCACHE protection modifier flags:

Flag	Meaning
PAGE_READONLY	Enables read access to the committed region of pages. An attempt to write to the committed region results in an access violation. If the system differentiates between read-only access and execute access, an attempt to execute code in the committed region results in an access violation.
PAGE_READWRITE	Enables both read and write access to the committed region of pages.
PAGE_WRITECOPY	Gives copy-on-write access to the committed region of pages.
PAGE_EXECUTE	Enables execute access to the committed region of pages. An attempt to read or write to the committed region results in an access violation.
PAGE_EXECUTE_READ	Enables execute and read access to the committed region of pages. An attempt to write to the committed region results in an access violation.
PAGE_EXECUTE_READWRITE	Enables execute, read, and write access to the committed region of pages.
PAGE_EXECUTE_WRITECOPY	Enables execute, read, and write access to the committed region of pages. The pages are shared read-on-write and copy-on-write.
PAGE_GUARD	Protects the page with the underlying page protection. However, access to the region causes a "guard page entered" condition to be raised in the subject process. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
PAGE_NOACCESS	Disables all access to the committed region of pages. An attempt to read from, write to, or execute in the committed region results in an access violation exception, called a general protection (GP) fault.
PAGE_NOCACHE	Allows no caching of the committed regions of pages. The hardware attributes for the physical memory should be set to no cache. This is not recommended for general usage. It is useful for device drivers; for example, mapping a video frame buffer with no caching. This flag is a page protection modifier, only valid when used with one of the page protections other than PAGE_NOACCESS.
RegionSize

Specifies the size, in bytes, of the region beginning at the base address in which all pages have identical attributes.

State

Specifies the state of the pages in the region. One of the following states is indicated:

State	Meaning
MEM_COMMIT	Indicates committed pages for which physical storage has been allocated, either in memory or in the paging file on disk.
MEM_FREE	Indicates free pages not accessible to the calling process and available to be allocated. For free pages, the information in the AllocationBase, AllocationProtect, Protect, and Type members is undefined.
MEM_RESERVE	Indicates reserved pages where a range of the process's virtual address space is reserved without allocating any physical storage. For reserved pages, the information in the Protect member is undefined.
Protect

Specifies the access protection of the pages in the region. One of the flags listed for the AllocationProtect member is specified.

Type

Specifies the type of pages in the region. The following types are defined:

Type	Meaning
MEM_IMAGE	Indicates that the memory pages within the region are mapped into the view of an image section.
MEM_MAPPED	Indicates that the memory pages within the region are mapped into the view of a section.
MEM_PRIVATE	Indicates that the memory pages within the region are private (not shared by other processes).
See Also

VirtualAlloc, VirtualQuery, VirtualQueryEx


MEMORYSTATUS

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.

Members

dwLength

Indicates the size of the structure. The calling process should set this member prior to calling GlobalMemoryStatus.

dwMemoryLoad

Specifies a number between 0 and 100 that gives a general idea of current memory utilization, in which 0 indicates no memory use and 100 indicates full memory use.

dwTotalPhys

Indicates the total number of bytes of physical memory.

dwAvailPhys

Indicates the number of bytes of physical memory available.

dwTotalPageFile

Indicates the total number of bytes that can be stored in the paging file. Note that this number does not represent the actual physical size of the paging file on disk.

dwAvailPageFile

Indicates the number of bytes available in the paging file.

dwTotalVirtual

Indicates the total number of bytes that can be described in the user mode portion of the virtual address space of the calling process.

dwAvailVirtual

Indicates the number of bytes of unreserved and uncommitted memory in the user mode portion of the virtual address space of the calling process.

See Also

GlobalMemoryStatus


MENU_EVENT_RECORD

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.

Members

dwCommandId

Used internally.

See Also

INPUT_RECORD


MENUEX_TEMPLATE_HEADER  (preliminaryWindows 95)
MENUEX_TEMPLATE_HEADER  (preliminary−Windows 95)

typedef struct

    WORD  wVersion;

    WORD  wOffset;

    DWORD dwHelpId;

} MENUEX_TEMPLATE_HEADER;

The MENUEX_TEMPLATE_HEADER structure defines the header for an extended menu template.

Members

wVersion

Template version number. This member must be 1 for extended menu templates.

wOffset

Offset of the first MENUEX_TEMPLATE_ITEM structure, relative to the end of this structure member. If the first item definition immediately follows the dwHelpId member, this member should be 4.

dwHelpId

Help identifier of menu bar

Remarks

An extended menu template consists of a MENUEX_TEMPLATE_HEADER structure followed by one or more contiguous MENUEX_TEMPLATE_ITEM structures. The MENUEX_TEMPLATE_ITEM structures, which are variable in length, are aligned on doubleword boundaries. To create a menu from an extended menu template in memory, use the LoadMenuIndirect function.

The structure definition given here is for explanation only; it is not present in any standard header file.

See Also

LoadMenuIndirect, MENUEX_TEMPLATE_ITEM


MENUEX_TEMPLATE_ITEM  (preliminaryWindows 95)
MENUEX_TEMPLATE_ITEM  (preliminary−Windows 95)

typedef struct {

    DWORD  dwType;

    DWORD  dwState;

    UINT   uId;

    BYTE   bResInfo;

    WCHAR  szText[1];

    // DWORD dwHelpId;

} MENUEX_TEMPLATE_ITEM;

The MENUEX_TEMPLATE_ITEM structure defines a menu item in an extended menu template.

Members

dwType

Menu item type. This member can be a combination of the type (beginning with MFT) values listed with the MENUITEMINFO structure.

dwState

Menu item state. This member can be a combination of the state (beginning with MFS) values listed with the MENUITEMINFO structure.

uId

Menu item identifier. This is an application-defined 16-bit value that identifies the menu item. In an extended menu resource, pop-up items as well as command items can have identifiers.

bResInfo

Value specifying whether the menu item is the last item in the menu bar or pop-up menu and whether it is a pop-up item. This member can be zero or more of these values:

Value	Meaning
MFR_END	The structure defines the last menu item in the menu bar or pop-up menu.
MFR_POPUP	The structure defines a pop-up item. Subsequent structures define menu items in the corresponding pop-up menu.
szText

Menu item text. This member, which is a null-terminated Unicode string, is aligned on a word boundary. The size of the menu item definition varies depending on the length of this string.

dwHelpId

Help identifier for a pop-up menu. This member, which is included only for pop-up items, is located at the first doubleword boundary following the variable-length szText member.

Remarks

An extended menu template consists of a MENUEX_TEMPLATE_HEADER structure followed by one or more contiguous MENUEX_TEMPLATE_ITEM structures. The MENUEX_TEMPLATE_ITEM structures, which are variable in length, are aligned on doubleword boundaries.

The structure definition given here is for explanation only; it is not present in any standard header file.

See Also

MENUEX_TEMPLATE_HEADER, MENUITEMINFO


MENUITEMINFO  (preliminaryWindows 95)
MENUITEMINFO  (preliminary−Windows 95)

typedef struct tagMENUITEMINFO {
    UINT    cbSize;

    UINT    fMask;

    UINT    fType;

    UINT    fState;

    UINT    wID;

    HMENU   hSubMenu;

    HBITMAP hbmpChecked;

    HBITMAP hbmpUnchecked;

    DWORD   dwItemData;

    LPTSTR  dwTypeData;

    UINT    cch;

} MENUITEMINFO, FAR *LPMENUITEMINFO;

The MENUITEMINFO structure contains information about a menu item.

Members

cbsize

Size of structure, in bytes.

fMask

Members to retrieve or set. This member can be one or more of these values:

Value	Meaning
MIIM_CHECKMARKS	Retrieves or sets the hbmpChecked and hbmpUnchecked members.
MIIM_DATA	Retrieves or sets the dwItemData member.
MIIM_ID	Retrieves or sets the wID member.
MIIM_STATE	Retrieves or sets the fState member.
MIIM_SUBMENU	Retrieves or sets the hSubMenu member.
MIIM_TYPE	Retrieves or sets the fType and dwTypeData members.
fType

Menu item type. This member can be one or more of these values:

Value	Meaning
MFT_BITMAP	Displays the menu item using a bitmap. The low-order word of the dwTypeData member is the bitmap handle, and the cch member is ignored.
MFT_MENUBARBREAK	Places the menu item on a new line if it is in a menu bar or in a new column if it is in a pop-up menu. A vertical line separates the new column from the old.
MFT_MENUBREAK	Places the menu item on a new line if it is in a menu bar or in a new column if it is in a pop-up menu. The columns are not separated by a vertical line.
MFT_OWNERDRAW	Assigns responsibility for drawing the menu item to the window that owns the menu. The window receives a WM_MEASUREITEM message before the menu is displayed for the first time, and a WM_DRAWITEM message whenever the appearance of the menu item must be updated. If this value is specified, the dwTypeData member contains an application-defined 32-bit value.
MFT_RADIOCHECK	Displays checked menu items using a radio-button mark instead of a check mark if the hbmpChecked member is NULL.
MFT_RIGHTJUSTIFY	Right-justifies the menu item and any subsequent items. This value is valid only if the menu item is in a menu bar.
MFT_SEPARATOR	Specifies that the menu item is a separator. A menu item separator appears as a horizontal dividing line. The dwTypeData and cch members are ignored. This value is valid only if the menu item is in a pop-up menu.
MFT_STRING	Displays the menu item using a text string. The dwTypeData member is the pointer to a null-terminated string, and the cch member is the length of the string.
The MFT_BITMAP, MFT_SEPARATOR, and MFT_STRING values cannot be combined with one another.

fState

Menu item state. This member can be one or more of these values:

Value	Meaning
MFS_CHECKED	Checks the menu item. For more information about checked menu items, see the hbmpChecked member.
MFS_DEFAULT	Specifies that the menu item is the default. A menu can contain only one default menu item, which is displayed in bold.
MFS_DISABLED	Disables the menu item so that it cannot be selected, but does not gray it.
MFS_ENABLED	Enables the menu item so that it can be selected. This is the default state.
MFS_GRAYED	Disables the menu item and grays it so that it cannot be selected.
MFS_HILITE	Highlights the menu item.
MFS_UNCHECKED	Unchecks the menu item. For more information about unchecked menu items, see the hbmpUnchecked member.
MFS_UNHILITE	Removes the highlight from the menu item. This is the default state.
wID

Application-defined 16-bit value that identifies the menu item.

hSubMenu

Handle to the pop-up menu associated with the menu item. If the menu item is not a pop-up item, this member is NULL.

hbmpChecked

Handle to the bitmap to display next to the item if it is checked. If this member is NULL, a default bitmap is used. If the MFT_RADIOCHECK type value is specified, the default bitmap is a bullet. Otherwise, it is a check mark.

hbmpUnchecked

Handle to the bitmap to display next to the item if it is not checked. If this member is NULL, no bitmap is used.

dwItemData

Application-defined value associated with the menu item.

dwTypeData

Content of the menu item. The meaning of this member depends on the menu item type: the MFT_BITMAP, MFT_SEPARATOR, or MFT_STRING values.

cch

Length of the menu item text, when information is received about a menu item of the MFT_STRING type. This value is zero for other menu item types. This member is ignored when the content of a menu item is set.

Remarks

The MENUITEMINFO structure is used with the GetMenuItemInfo, InsertMenuItem, and SetMenuItemInfo functions.

See Also

GetMenuItemInfo, InsertMenuItem, SetMenuItemInfo, WM_DRAWITEM, WM_MEASUREITEM


MENUITEMTEMPLATE

typedef struct {    // mit

    WORD mtOption;       // menu item flags

    WORD mtID;           // menu item identifier (omitted for pop-up items)

    WCHAR mtString[1];   // null-terminated string for menu item

} MENUITEMTEMPLATE;

The MENUITEMTEMPLATE structure defines a menu item in a menu template.

Members

mtOption

Specifies one or more of the following predefined menu options that control the appearance of the menu item:

Value	Meaning
MF_CHECKED	Indicates that the menu item has a check mark next to it.
MF_GRAYED	Indicates that the menu item is initially inactive and drawn with a gray effect.
MF_HELP	Indicates that the menu item has a vertical separator to its left.
MF_MENUBARBREAK	Indicates that the menu item is placed in a new column. The old and new columns are separated by a bar.
MF_MENUBREAK	Indicates that the menu item is placed in a new column.
MF_OWNERDRAW	Indicates that the owner window of the menu is responsible for drawing all visual aspects of the menu item, including highlighted, checked, and inactive states. This option is not valid for an item in a menu bar.
MF_POPUP	Indicates that the item is 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 item does not contain the mtID member.

mtString

Specifies the null-terminated string for the menu item.

See Also

LoadMenuIndirect, MENUITEMTEMPLATEHEADER


MENUITEMTEMPLATEHEADER

typedef struct {          // mith

    WORD versionNumber;   // version number; must be zero

    WORD offset;          // offset first MENUITEMTEMPLATE structure

} 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.

Members

versionNumber

Specifies the version number. This member must be zero.

offset

Specifies the offset, in bytes, from the end of the header. The menu item list begins at this offset. Usually, this member is zero, and the menu item list follows immediately after the header.

Remarks

One or more MENUITEMTEMPLATE structures are combined to form the menu item list.

See Also

LoadMenuIndirect, MENUITEMTEMPLATE


METAFILEPICT

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.

Members

mm

Specifies the mapping mode in which the picture is drawn.

xExt

Specifies the size of the metafile picture for all modes except the MM_ISOTROPIC and MM_ANISOTROPIC modes. (For more information about these modes, see the yExt member.) The x-extent specifies the width of the rectangle within which the picture is drawn. The coordinates are in units that correspond to the mapping mode.

yExt

Specifies the size of the metafile picture for all modes except the MM_ISOTROPIC and MM_ANISOTROPIC modes. The y-extent specifies the height of the rectangle within which the picture is drawn. The coordinates are in units that correspond to the mapping mode.

For MM_ISOTROPIC and MM_ANISOTROPIC modes, which can be scaled, the xExt and yExt members contain an optional suggested size in MM_HIMETRIC units. For MM_ANISOTROPIC pictures, xExt and yExt can be zero when no suggested size is supplied. For MM_ISOTROPIC pictures, an aspect ratio must be supplied even when no suggested size is given. (If a suggested size is given, the aspect ratio is implied by the size.) To give an aspect ratio without implying a suggested size, set xExt and yExt to negative values whose ratio is the appropriate aspect ratio. The magnitude of the negative xExt and yExt values is ignored; only the ratio is used.

hMF

Identifies a memory metafile.

See Also

SetClipboardData


METAHEADER

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 Windows-format metafile.

Members

mtType

Specifies whether the metafile is in memory or recorded in a disk file. This member can be one of the following values:

Value	Meaning
1	Metafile is in memory.
2	Metafile is in a disk file.
mtHeaderSize

Specifies the size, in words, of the metafile header.

mtVersion

Specifies the Windows version number. The version number for metafiles that support device-independent bitmaps (DIBs) is 0x0300. Otherwise, the version number is 0x0100.

mtSize

Specifies the size, in words, of the file.

mtNoObjects

Specifies the maximum number of objects that exist in the metafile at the same time.

mtMaxRecord

Specifies the size, in words, of the largest record in the metafile.

mtNoParameters

Reserved.

See Also

METARECORD


METARECORD

typedef struct tagMETARECORD {  // mr

    DWORD rdSize;

    WORD  rdFunction;

    WORD  rdParm[1];

} METARECORD;

The METARECORD structure contains a Windows-format metafile record.

Members

rdSize

Specifies the size, in words, of the record.

rdFunction

Specifies the function number.

rdParm

Specifies an array of words containing the function parameters, in reverse of the order they are passed to the function.

See Also

METAHEADER


MINMAXINFO

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.

Members

ptReserved

Reserved; do not use.

ptMaxSize

Specifies the maximized width (point.x) and the maximized height (point.y) of the window.

ptMaxPosition

Specifies the position of the left side of the maximized window (point.x) and the position of the top of the maximized window (point.y).

ptMinTrackSize

Specifies the minimum tracking width (point.x) and the minimum tracking height (point.y) of the window.

ptMaxTrackSize

Specifies the maximum tracking width (point.x) and the maximum tracking height (point.y) of the window.

See Also

POINT, WM_GETMINMAXINFO


MINIMIZEDMETRICS

typedef struct tagMINIMIZEDMETRICS {

    UINT    cbSize;

    int     iWidth;

    int     iHorzGap;

    int     iVertGap;

    int     iArrange;

}   MINIMIZEDMETRICS, FAR *LPMINIMIZEDMETRICS;

The MINIMIZEDMETRICS structure contains the scalable metrics associated with minimized windows. This structure is used with the SystemParametersInfo function when the SPI_GETMINIMIZEDMETRICS or SPI_SETMINIMIZEDMETRICS action value is specified.

Members

cbSize

Specifies the size of the structure, in bytes.

iWidth

Specifies the width, in pixels, of minimized windows.

iHorzGap and iVertGap

Specifies the amount of horizontal and vertical space, in pixels, between arranged minimized windows.

iArrange

Specifies the starting position and direction used when arranging minimized windows. The starting position must be one of the following values:

Value	Meaning
ARW_BOTTOMLEFT	Start at the lower-left corner of the work area.
ARW_BOTTOMRIGHT	Start at the lower-right corner of the work area.
ARW_TOPLEFT	Start at the upper-left corner of the work area.
ARW_TOPRIGHT	Start at the upper-right corner of the work area.
The direction must be one of the following values:

Value	Meaning
ARW_LEFT	Arrange left (valid with ARW_BOTTOMRIGHT and ARW_TOPRIGHT only).
ARW_RIGHT	Arrange right (valid with ARW_BOTTOMLEFT and ARW_TOPLEFT only).
ARW_UP	Arrange up (valid with ARW_BOTTOMLEFT and ARW_BOTTOMRIGHT only).
ARW_DOWN	Arrange down (valid with ARW_TOPLEFT and ARW_TOPRIGHT only).
See Also

SystemParametersInfo


MODEMDEVCAPS  (preliminaryWindows 95)
MODEMDEVCAPS

typedef struct modemdevcaps_tag {
    DWORD dwActualSize;               // size of returned data, in bytes
    DWORD dwRequiredSize;             // total size of structure
    DWORD dwDevSpecificOffset;        // offset of provider-defined data
    DWORD dwDevSpecificSize;          // size of provider-defined data

    // Product and version identification
    DWORD dwModemProviderVersion;     // provider version number
    DWORD dwModemManufacturerOffset;  // offset of manufacturer name
    DWORD dwModemManufacturerSize;    // length of manufacturer name
    DWORD dwModemModelOffset;         // offset of model name
    DWORD dwModemModelSize;           // length of model name
    DWORD dwModemVersionOffset;       // offset of version name
    DWORD dwModemVersionSize;         // length of version name

    // Local option capabilities
    DWORD dwDialOptions;              // bitmap of supported values
    DWORD dwCallSetupFailTimer;       // maximum in seconds
    DWORD dwInactivityTimeout;        // maximum in tenths of seconds
    DWORD dwSpeakerVolume;            // bitmap of supported values
    DWORD dwSpeakerMode;              // bitmap of supported values
    DWORD dwModemOptions;             // bitmap of supported values
    DWORD dwMaxDTERate;               // maximum value in bit/s
    DWORD dwMaxDCERate;               // maximum value in bit/s

    // Variable portion for strings and provider-specific data
    BYTE abVariablePortion [1];       // variable-length data
} MODEMDEVCAPS, *PMODEMDEVCAPS, *LPMODEMDEVCAPS;

The MODEMDEVCAPS structure contains information about the capabilities of a modem.

Members

dwActualSize

Specifies the size, in bytes, of the data actually returned to the application. This member may be less than the dwRequiredSize member, if an application did not allocate enough space for the variable-length portion of the structure.

dwRequiredSize

Specifies the number of bytes required for the entire MODEMDEVCAPS structure, including the variable-length portion.

dwDevSpecificOffset

Specifies the offset of the provider-defined portion of the structure, in bytes relative to the beginning of the structure.

dwDevSpecificSize

Specifies the size of the provider-defined portion of the structure, in bytes.

dwModemProviderVersion

Specifies the version of the service provider. The format and use of this member depends on the service provider.

dwModemManufacturerOffset

Specifies the offset of a text string that contains the name of the modem manufacturer. The offset is specified in bytes relative to the beginning of the structure.

dwModemManufacturerSize

Specifies the length of the modem manufacturer name, in bytes. The string is not null-terminated.

dwModemModelOffset

Specifies the offset of a text string that contains the model of the modem. The offset is specified in bytes relative to the beginning of the structure.

dwModemModelSize

Specifies the length of the model name, in bytes. The string is not null-terminated.

dwModemVersionOffset

Specifies the offset of a text string that gives the version and revision of the attached modem, if the provider could determine the information. The offset is specified in bytes relative to the beginning of the structure.

dwModemVersionSize

Specifies the length of the modem version string, in bytes. The string is not null-terminated.

dwDialOptions

Specifies dialing options that are supported by the modem device. This member can be zero or more of the following values:

Value	Meaning
DIALOPTION_DIALBILLING	Specifies that the modem supports waiting for billing tone (bong).
DIALOPTION_DIALQUIET	Specifies that the modem supports waiting for quiet.
DIALOPTION_DIALDIALTONE	Specifies that the modem supports waiting for a dial tone.
dwCallSetupFailTimer

Specifies the maximum call setup timeout supported by the modem, in seconds. This is the largest value that can be specified for the corresponding member of the MODEMSETTINGS structure.

dwInactivityTimeout

Specifies the maximum inactivity timeout supported by the modem, in tenths of seconds. This is the largest value that can be specified for the corresponding member of the MODEMSETTINGS structure.

dwSpeakerVolume

Specifies the speaker volume settings supported by the modem. This member can be zero or more of the following values:

Value	Meaning
MDMVOLFLAG_LOW	The modem supports low (MDMVOL_LOW) volume.
MDMVOLFLAG_MEDIUM	The modem supports medium (MDMVOL_MEDIUM) volume.
MDMVOLFLAG_HIGH	The modem supports high (MDMVOL_HIGH) volume.
dwSpeakerMode

Specifies the speaker mode settings supported by the modem. This member can be zero or more of the following values:

Value	Meaning
MDMSPKRFLAG_OFF	The modem supports the MDMSPKR_OFF speaker mode.
MDMSPKRFLAG_DIAL	The modem supports the MDMSPKR_DIAL speaker mode.
MDMSPKRFLAG_ON	The modem supports the MDMSPKR_ON speaker mode.
MDMSPKRFLAG_CALLSETUP	The modem supports the MDMSPKR_CALLSETUP speaker mode.
dwModemOptions

Specifies supported modem options. This member can be zero or more of the following values:

MDM_BLIND_DIAL	MDM_FLOWCONTROL_SOFT
MDM_CCITT_OVERRIDE	MDM_FORCED_EC
MDM_CELLULAR	MDM_SPEED_ADJUST
MDM_COMPRESSION	MDM_TONE_DIAL
MDM_ERROR_CONTROL	MDM_V23_OVERRIDE
MDM_FLOWCONTROL_HARD
When MODEMDEVCAPS is used to set modem options, as part of the MODEMSETTINGS structure, these values are used as follows:

Value	Meaning
MDM_CCITT_OVERRIDE	When set, CCITT modulations are enabled for V.21 and V.22 or V.23. When clear, bell modulations are enabled for 103 and 212A.
MDM_V23_OVERRIDE	When set, CCITT modulations are enabled for V.23. When clear, CCITT modulations are enabled for V.21 and V.22.
For V.23 to be set, both MDM_CCITT_OVERRIDE and MDM_V23_OVERRIDE must be set.

dwMaxDTERate

Maximum DTE rate in bits per second.

dwMaxDCERate

Maximum DCE rate in bits per second.

abVariablePortion

Contains variable-length information, including strings and any provider-defined information.

See Also

MODEMSETTINGS


MODEMSETTINGS  (preliminaryWindows 95)
MODEMSETTINGS

typedef struct modemsettings_tag {
    DWORD dwActualSize;               // size of returned data, in bytes
    DWORD dwRequiredSize;             // total size of structure
    DWORD dwDevSpecificOffset;        // offset of provider-defined data
    DWORD dwDevSpecificSize;          // size of provider-defined data

    // Static local options (read/write)
    DWORD dwCallSetupFailTimer;       // call setup timeout, in seconds
    DWORD dwInactivityTimeout;        // inactivity timeout, in tenths of seconds
    DWORD dwSpeakerVolume;            // speaker volume level
    DWORD dwSpeakerMode;              // speaker mode
    DWORD dwPreferredModemOptions;    // bitmap specifying preferred options

    // negotiated options (read only) for current or last call
    DWORD dwNegotiatedModemOptions;   // bitmap specifying actual options
    DWORD dwNegotiatedDCERate;        // DCE rate, in bits per second

    // Variable portion for proprietary expansion
    BYTE  abVariablePortion[1];       // variable-length data
} MODEMSETTINGS, *PMODEMSETTINGS, *LPMODEMSETTINGS;

The MODEMSETTINGS structure contains information about a modem's configuration.

Members

dwActualSize

Specifies the size, in bytes, of the data actually returned to the application. This member may be less than the dwRequiredSize member if an application did not allocate enough space for the variable-length portion of the structure.

dwRequiredSize

Specifies the number of bytes required for the entire MODEMDEVCAPS structure, including the variable-length portion.

dwDevSpecificOffset

Specifies the offset of the provider-defined portion of the structure, in bytes relative to the beginning of the structure.

dwDevSpecificSize

Specifies the size of the provider-defined portion of the structure, in bytes.

dwCallSetupFailTimer

Specifies the maximum number of seconds the modem should wait, after dialing is completed, for an indication that a modem-to-modem connection has been established. If a connection is not established in this interval, the call is assumed to have failed. This member is equivalent to register S7 in Hayes® compatible modems.

dwInactivityTimeout

Specifies the maximum number of seconds of inactivity allowed after a connection is established. If no data is either transmitted or received for this period of time, the call is automatically terminated. This time-out is used to avoid excessive long distance charges or online service charges if an application unexpectedly locks up or the user leaves.

dwSpeakerVolume

Specifies the volume level of the monitor speaker when the speaker is on. This member can be one of the following values:

Value	Meaning
MDMVOL_LOW	Low volume.
MDMVOL_MEDIUM	Medium volume.
MDMVOL_HIGH	High volume.
The MODEMDEVCAPS structure specifies the speaker volumes a modem supports. Actual volumes are hardware-specific.

dwSpeakerMode

Specifies when the speaker should be on. This member can be one of the following values:

Value	Meaning
MDMSPKR_OFF	The speaker is always off.
MDMSPKR_CALLSETUP	The speaker is on until a connection is established.
MDMSPKR_ON	The speaker is always on.
MDMSPKR_DIAL	The speaker is on until a connection is established, except that it is off while the modem is actually dialing.
dwPreferredModemOptions

Specifies the modem options requested by the application. The local and remote modems negotiate modem options during call setup; this member specifies the initial negotiating position of the local modem.

The dwModemOptions member of the MODEMDEVCAPSstructure specifies the modem options supported by the local modem. For a list of modem options, see the description of the MODEMDEVCAPS structure.

dwNegotiatedModemOptions

Specifies the modem options that are actually in effect. This member is filled in after a connection is established and the local and remote modems negotiate modem options.

The dwModemOptions member of the MODEMDEVCAPS structure specifies the modem options supported by the local modem. For a list of modem options, see the description of the MODEMDEVCAPS structure.

dwNegotiatedDCERate

Specifies the DCE rate that is in effect. This member is filled in after a connection is established and the local and remote modems negotiate modem modulations.

abVariablePortion

Contains provider-defined information, if any.

See Also

MODEMDEVCAPS


MONCBSTRUCT

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 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.

Members

cb

Specifies the structure's size, in bytes.

dwTime

Specifies the Windows time that the transaction occurred. Windows time is the number of milliseconds that have elapsed since the system was booted.

hTask

Identifies the task (application instance) containing the DDE callback function that received the transaction.

dwRet

Specifies the value returned by the DDE callback function that processed the transaction.

wType

Identifies the transaction type.

wFmt

Specifies the format of the data exchanged (if any) during the transaction.

hConv

Identifies the conversation in which the transaction took place.

hsz1

Identifies a string.

hsz2

Identifies a string.

hData

Identifies the data exchanged (if any) during the transaction.

dwData1

Specifies additional data.

dwData2

Specifies additional data.

cc

Specifies a CONVCONTEXT structure containing language information used to share data in different languages.

cbData

Specifies the amount, in bytes, of data being passed with the transaction. This value may be more than 32 bytes.

Data

Contains the first 32 bytes of data being passed with the transaction
(8 * sizeof(DWORD)).

See Also

CONVCONTEXT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


MONCONVSTRUCT

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 DDE conversation. A DDE monitoring application can use this structure to obtain information about a conversation that has been established or has terminated.

Members

cb

Specifies the structure's size, in bytes.

fConnect

Indicates whether the conversation is currently established. A value of TRUE indicates the conversation is established; FALSE indicates it is not.

dwTime

Specifies the Windows time at which the conversation was established or terminated. Windows time is the number of milliseconds that have elapsed since the system was booted.

hTask

Identifies a task (application instance) that is a partner in the conversation.

hszSvc

Identifies the service name on which the conversation is established.

hszTopic

Identifies the topic name on which the conversation is established.

hConvClient

Identifies the client conversation.

hConvServer

Identifies the server conversation.

Remarks

Because string handles are local to the process, the hszSvc and hszTopic members are global atoms. Similarly, conversation handles are local to the instance; therefore, the hConvClient and hConvServer members are window handles.

The hConvClient and hConvServer members of the MONCONVSTRUCT structure do not hold the same value as would be seen by the applications engaged in the conversation. Instead, they hold a globally unique pair of values that identify the conversation.

See Also

MONCBSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


MONERRSTRUCT

typedef struct tagMONERRSTRUCT { // mest

    UINT   cb;

    UINT   wLastError;

    DWORD  dwTime;

    HANDLE hTask;

} MONERRSTRUCT;

The MONERRSTRUCT structure contains information about the current DDE error. A DDE monitoring application can use this structure to monitor errors returned by DDE Management Library functions.

Members

cb

Specifies the structure's size, in bytes.

wLastError

Identifies the current error.

dwTime

Specifies the Windows time that the error occurred. Windows time is the number of milliseconds that have elapsed since the system was booted.

hTask

Identifies the task (application instance) that called the DDE function that caused the error.

See Also

MONCBSTRUCT, MONCONVSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


MONHSZSTRUCT

typedef struct tagMONHSZSTRUCT { // mhst

    UINT   cb;

    BOOL   fsAction;

    DWORD  dwTime;

    HSZ    hsz;

    HANDLE hTask;

    TCHAR   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.

Members

cb

Specifies the structure's size, in bytes.

fsAction

Specifies the action being performed on the string identified by the hsz member.

Value	Meaning
MH_CLEANUP	An application is freeing its DDE resources, causing the system to delete string handles the application had created. (The application called the DdeUninitialize function.)
MH_CREATE	An application is creating a string handle. (The application called the DdeCreateStringHandle function.)
MH_DELETE	An application is deleting a string handle. (The application called the DdeFreeStringHandle function.)
MH_KEEP	An application is increasing the usage count of a string handle. (The application called the DdeKeepStringHandle function.)
dwTime

Specifies the Windows time when the action specified by the fsAction member takes place. Windows time is the number of milliseconds that have elapsed since the system was booted.

hsz

Identifies the string. Because string handles are local to the process, this member is a global atom.

hTask

Identifies the task (application instance) performing the action on the string handle.

str

Points to the string identified by the hsz member.

See Also

MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


MONITOR_INFO_1

typedef struct _MONITOR_INFO_1 { // mi1

    LPTSTR pName;

} MONITOR_INFO_1;

The MONITOR_INFO_1 structure identifies an installed monitor.

Members

pName

Points to a null-terminated string that identifies an installed monitor.

See Also

EnumMonitors, MONITOR_INFO_2


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.

Members

pName

Points to a null-terminated string that is the name of the monitor.

pEnvironment

Points to a null-terminated environment string specifying the environment in which the monitor dynamic-link library (DLL) is designed to run.

pDLLName

Points to a null-terminated string that is the name of the monitor DLL.

See Also

EnumMonitors, MONITOR_INFO_1


MONLINKSTRUCT

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 DDE advise loop. A DDE monitoring application can use this structure to obtain information about an advise loop that has started or ended.

Members

cb

Specifies the structure's size, in bytes.

dwTime

Specifies the Windows time when the advise loop was started or ended. Windows time is the number of milliseconds that have elapsed since the system was booted.

hTask

Identifies a task (application instance) that is a partner in the advise loop.

fEstablished

Indicates whether an advise loop was successfully established. A value of TRUE indicates an advise loop was established; FALSE indicates it was not.

fNoData

Indicates whether the XTYPF_NODATA flag is set for the advise loop. A value of TRUE indicates the flag is set; FALSE indicates it is not.

hszSvc

Identifies the service name of the server in the advise loop.

hszTopic

Identifies the topic name on which the advise loop is established.

hszItem

Identifies the item name that is the subject of the advise loop.

wFmt

Specifies the format of the data exchanged (if any) during the advise loop.

fServer

Indicates whether the link notification came from the server. A value of TRUE indicates the notification came from the server; FALSE indicates otherwise.

hConvServer

Identifies the server conversation.

hConvClient

Identifies the client conversation.

Remarks

Because string handles are local to the process, the hszSvc, hszTopic, and hszItem members are global atoms.

The hConvClient and hConvServer members of the MONLINKSTRUCT structure do not hold the same value as would be seen by the applications engaged in the conversation. Instead, they hold a globally unique pair of values that identify the conversation.

See Also

MONCBSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONMSGSTRUCT


MONMSGSTRUCT

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.

Members

cb

Specifies the structure's size, in bytes.

hwndTo

Identifies the window that receives the DDE message.

dwTime

Specifies the Windows time at which the message was sent or posted. Windows time is the number of milliseconds that have elapsed since the system was booted.

hTask

Identifies the task (application instance) containing the window that receives the DDE message.

wMsg

Specifies the identifier of the DDE message.

wParam

Specifies the wParam parameter of the DDE message.

lParam

Specifies the lParam parameter of the DDE message.

dmhd

Specifies a DDEML_MSG_HOOK_DATA structure that contains additional information about the DDE message.

See Also

DDEML_MSG_HOOK_DATA, MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT


MOUSE_EVENT_RECORD

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.

Members

dwMousePosition

Specifies the location of the cursor in terms of the screen buffer's character-cell coordinates.

dwButtonState

Indicates the status of the mouse buttons. The least significant bit corresponds to the leftmost mouse button. The next least significant bit corresponds to the rightmost mouse button. The next bit indicates the next-to-leftmost mouse button. The bits then correspond left to right to the mouse buttons. A bit is 1 if the button was pressed.

The following constants are defined for the first five mouse buttons:

FROM_LEFT_1ST_BUTTON_PRESSED

RIGHTMOST_BUTTON_PRESSED

FROM_LEFT_2ND_BUTTON_PRESSED

FROM_LEFT_3RD_BUTTON_PRESSED

FROM_LEFT_4TH_BUTTON_PRESSED

dwControlKeyState

Indicates the state of the control keys. This member can be a combination of the following values:

Value	Meaning
RIGHT_ALT_PRESSED	The right ALT key is pressed.
LEFT_ALT_PRESSED	The left ALT key is pressed.
RIGHT_CTRL_PRESSED	The right CTRL key is pressed.
LEFT_CTRL_PRESSED	The left CTRL key is pressed.
CAPSLOCK_ON	The CAPS LOCK light is on.
ENHANCED_KEY	The key is enhanced.
NUMLOCK_ON	The NUM LOCK light is on.
SCROLLLOCK_ON	The SCROLL LOCK light is on.
SHIFT_PRESSED	The SHIFT key is pressed.
dwEventFlags

Indicates the type of mouse event. If this value is zero, it indicates a mouse button being pressed or released. Otherwise, the value is one of the following:

Value	Meaning
DOUBLE_CLICK	The second click (button press) of a double-click occurred. The first click is returned as a regular button-press event.
MOUSE_MOVED	A change in mouse position occurred.
Remarks

Mouse events are placed in the input buffer when the console is in mouse mode (ENABLE_MOUSE_INPUT).

Mouse events are generated whenever the user moves the mouse, or presses or releases one of the mouse buttons. Mouse events are placed in a console's input buffer only when the console group has the keyboard focus and the cursor is within the borders of the console's window.

See Also

INPUT_RECORD, PeekConsoleInput, ReadConsoleInput, WriteConsoleInput


MOUSEHOOKSTRUCT

typedef struct tagMOUSEHOOKSTRUCT { // ms

    POINT pt;

    HWND  hwnd;

    UINT  wHitTestCode;

    DWORD dwExtraInfo;

} MOUSEHOOKSTRUCT;

The MOUSEHOOKSTRUCT structure contains information about a mouse event.

Members

pt

Specifies a POINT structure that contains the x- and y-coordinates of the cursor, in screen coordinates.

hwnd

Identifies the window that will receive the mouse message corresponding to the mouse event.

wHitTestCode

Specifies the hit-test value. For a list of hit-test values, see the description of the WM_NCHITTEST message.

dwExtraInfo

Specifies extra information associated with the message.

See Also

GetMessageExtraInfo, POINT, SetWindowsHook, SetWindowsHookEx, WM_NCHITTEST


MOUSEKEYS

typedef struct _MOUSEKEYS {     // mk

    DWORD cbSize;

    DWORD dwFlags;

    DWORD iMaxSpeed;

    DWORD iTimeToMaxSpeed;

    DWORD iCtrlSpeed;

    DWORD dwReserved1;

    DWORD dwReserved2;

} MOUSEKEYS;

The MOUSEKEYS structure contains information about the MouseKeys accessibility feature. When the MouseKeys feature is active, the user can use the numeric keypad to control the mousepointer, and to click, double-click, drag, and drop. By pressing NUMLOCK, the user can toggle the numeric keypad between mouse control mode and normal operation.

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

A set of bit-flags that specify properties of the FilterKeys feature. The following bit-flag values are defined:

Value	Meaning
MKF_AVAILABLE	If this flag is set, the MouseKeys feature is available.
MKF_CONFIRMHOTKEY	Windows 95 only: A confirmation dialog box appears when the MouseKeys feature is activated by using the hot key.
MKF_HOTKEYACTIVE	If this flag is set, the user can turn the MouseKeys feature on and off by using the hot key, which is LEFT ALT+LEFT SHIFT+NUM LOCK.
MKF_HOTKEYSOUND	If this flag is set, the system plays a siren sound when the user turns the MouseKeys feature on or off by using the hot key.
MKF_INDICATOR	Windows 95 only: A visual indicator is displayed when the MouseKeys feature is on.
MKF_MOUSEKEYSON	If this flag is set, the MouseKeys feature is on.
MKF_MODIFIERS	Windows 95 only: The CTRL key increases cursor speed by the value specified by the iCtrlSpeed member, and the SHIFT key causes the cursor to delay briefly after moving a single pixel, allowing fine positioning of the cursor. If this value is not specified, the CTRL and SHIFT keys are ignored while the user moves the mouse cursor using the arrow keys.
MKF_REPLACENUMBERS	Windows 95 only:The numeric keypad moves the mouse when the NUM LOCK key is on. If this flag is not specified, the numeric keypad moves the mouse cursor when the NUM LOCK key is off.
iMaxSpeed

Specifies the maximum speed the mouse cursor attains when an arrow key is held down.

Windows 95: Range checking is not performed.

Windows NT: Valid values are from 10 to 360.

iTimeToMaxSpeed

Specifies the length of time, in milliseconds, that it takes for the mouse cursor to reach maximum speed when an arrow key is held down. Valid values are from 1000 to 5000.

iCtrlSpeed

Windows 95: Specifies the multiplier to apply to the mouse cursor speed when the user holds down the ctrl key while using the arrow keys to move the cursor. this value is ignored if MKF_MODIFIERS is not set.

Windows NT: This member is reserved for future use. It must be set to zero.

dwReserved1

This member is reserved for future use. It must be set to zero.

dwReserved2

This member is reserved for future use. It must be set to zero.

Remarks

An application uses a MOUSEKEYS structure when calling the SystemParametersInfo function with the wAction parameter set to the SPI_GETMOUSEKEYS or SPI_SETMOUSEKEYS value. When using SPI_GETMOUSEKEYS, an application must specify the cbSize member of the MOUSEKEYS structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SPI_SETMOUSEKEYS value.

See Also

SystemParametersInfo


MSG

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.

Members

hwnd

Identifies the window whose window procedure receives the message.

message

Specifies the message number.

wParam

Specifies additional information about the message. The exact meaning depends on the value of the message member.

lParam

Specifies additional information about the message. The exact meaning depends on the value of the message member.

time

Specifies the time at which the message was posted.

pt

Specifies the cursor position, in screen coordinates, when the message was posted.

See Also

GetMessage, PeekMessage


MSGBOXPARAMS  (preliminaryWindows 95)
MSGBOXPARAMS  (preliminary−Windows 95)

typedef struct {

    UINT      cbSize;

    HWND      hwndOwner;

    HINSTANCE hInstance;

    LPCSTR    lpszText;

    LPCSTR    lpszCaption;

    DWORD     dwStyle;

    LPCSTR    lpszIcon;

    DWORD     dwContextHelpId;

    MSGBOXCALLBACK lpfnMsgBoxCallback;

    DWORD     dwLanguageId;

} MSGBOXPARAMS, *PMSGBOXPARAMS, FAR *LPMSGBOXPARAMS;

The MSGBOXPARAMS structure contains information used to display a message box. The MessageBoxIndirect function uses this structure.

Members

cbSize

Specifies the structure size, in bytes.

hwndOwner

Identifies the owner window; can be NULL.

hInstance

Identifies the instance containing the icon resource identified by the lpszIcon member, and the string resource identified by the lpszText or lpszCaption member.

lpszText

Points to a null-terminated string, or the identifier of a string resource, that contains the message to be displayed.

lpszCaption

Points to a null-terminated string, or the identifier of a string resource, that contains the message box title. If this member is NULL, the default title Error is used.

dwStyle

Specifies the contents and behavior of the message box. Can be one or more of the values specified in the MessageBoxEx function and one of the following values:

Value	Meaning
MB_HELP	Adds a Help button to the message box. Choosing the Help button or pressing F1 generates a Help event.
MB_TOPMOST	Uses the WS_EX_TOPMOST window style.
MB_USERICON	Uses the icon specified by the lpszIcon member.
lpszIcon

Identifies an icon resource. This parameter can be either a null-terminated string or an integer resource identifier passed to the MAKEINTRESOURCE macro. To load a standard icon, the hInstance member should be NULL, and lpszIcon should be one of the values listed with the LoadIcon function. This parameter is ignored if the dwStyle member does not specify the MB_USERICON flag.

dwContextHelpId

Identifies a Help context. If a Help event occurs, this value is specified in the HELPINFO structure that the message box sends to the owner window or callback function.

lpfnMsgBoxCallback

Points to the callback function that processes Help events for the message box. The callback function has the following form:

VOID CALLBACK MsgBoxCallback(LPHELPINFO lpHelpInfo);

If this member is NULL, the message box sends WM_HELP messages to the owner window when help events occur.

dwLanguageId

Specifies the language in which to display the text contained in the predefined push buttons. This value must be in the form returned by the MAKELANGID macro.

See Also

HELPINFO, LoadIcon, MAKEINTRESOURCE, MAKELANGID, MessageBoxEx, MessageBoxIndirect


MSGFILTER  (preliminaryWindows NT)
MSGFILTER  (preliminary−Windows NT)

typedef struct _msgfilter {

    NMHDR nmhdr;

    UINT msg;

    _WPAD _wPad1;

    WPARAM wParam;

    _WPAD _wPad2;

    LPARAM lParam;

} MSGFILTER;

The MSGFILTER structure contains information about a keyboard or mouse event. A rich edit control sends this structure to its parent window as part of an EN_MSGFILTER notification message, enabling the parent to change the message or prevent it from being processed.

Members

nmhdr

Notification header.

msg

Keyboard or mouse message identifier.

wParam

wParam parameter of the message.

lParam

lParam parameter of the message.

See Also

EN_MSGFILTER


MULTIKEYHELP

typedef struct tagMULTIKEYHELP { // mkh

    DWORD  mkSize;

    TCHAR  mkKeylist;

    TCHAR  szKeyphrase[1];

} MULTIKEYHELP;

The MULTIKEYHELP structure specifies a keyword table and an associated keyword to be used by Windows Help.

Members

mkSize

Specifies the structure size, in bytes.

mkKeylist

Specifies a single character that identifies the keyword table to search.

szKeyphrase

Contains a null-terminated text string that specifies the keyword to locate in the keyword table.

See Also

WinHelp


NAME_BUFFER

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 the NCBASTAT command in the ncb_command member of the NCB structure.

Members

name

Specifies the local network name. This value is in the ncb_name member of the NCB structure.

name_num

Specifies the number for the local network name. This value is in the ncb_num member of the NCB structure.

name_flags

Specifies the current state of the name table entry. This member can be one of the following values:

Value	Meaning
REGISTERING	The name specified by the name member is being added to the network.
REGISTERED	The name specified by the name member has been successfully added to the network.
DEREGISTERED	The name specified by the name member has an active session when an NCBDELNAME command is issued. The name will be removed from the name table when the session is closed.
DUPLICATE	A duplicate name was detected during registration.
DUPLICATE_DEREG	A duplicate name was detected with a pending deregistration.
GROUP_NAME	The name specified by the name member was created by using the NCBADDGRNAME command.
UNIQUE_NAME	The name specified by the name member was created by using the NCBADDNAME command.
See Also

ADAPTER_STATUS, NCB


NCB

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.

Members

ncb_command

Specifies the command code and a flag that indicates whether the NCB structure is processed asynchronously. The most significant bit contains the flag. If the ASYNCH constant is combined with a command code (by using the OR operator), the NCB structure is processed asynchronously. The following command codes are supported:

Code	Meaning
NCBACTION	Enables extensions to the transport interface. NCBACTION commands are mapped to TdiAction. When this code is specified, the ncb_buffer member points to a buffer to be filled with an ACTION_HEADER structure, which is optionally followed by data. NCBACTION commands cannot be canceled by using NCBCANCEL.
NCBADDGRNAME	Adds a group name to the local name table.
NCBADDNAME	Adds a unique name to the local name table.
NCBASTAT	Retrieves the status of the adapter. When this code is specified, the ncb_buffer member points to a buffer to be filled with an ADAPTER_STATUS structure, followed by an array of NAME_BUFFER structures.
NCBCALL	Opens a session with another name.
NCBCANCEL	Cancels a previous command.
NCBCHAINSEND	Sends the contents of two data buffers to the specified session partner. For Windows NT, this is equivalent to the NCBCHAINSENDNA command.
NCBCHAINSENDNA	Sends the contents of two data buffers to the specified session partner and does not wait for acknowledgment. For Windows NT, this is equivalent to the NCBCHAINSEND command.
NCBDELNAME	Deletes a name from the local name table.
NCBDGRECV	Receives a datagram from any name.
NCBDGRECVBC	Receives broadcast datagram from any host.
NCBDGSEND	Sends datagram to a specified name.
NCBDGSENDBC	Sends a broadcast datagram to every host on the local area network (LAN).
NCBENUM	Enumerates LAN adapter (LANA) numbers. When this code is specified, the ncb_buffer member points to a buffer to be filled with a LANA_ENUM structure.
NCBFINDNAME	Determines the location of a name on the network. When this code is specified, the ncb_buffer member points to a buffer to be filled with a FIND_NAME_HEADER structure followed by one or more FIND_NAME_BUFFER structures.
NCBHANGUP	Closes a specified session.
NCBLANSTALERT	Notifies the user of LAN failures that last for more than one minute.
NCBLISTEN	Enables a session to be opened with another name.
NCBRECV	Receives data from the specified session partner.
NCBRECVANY	Receives data from any session corresponding to a specified name.
NCBRESET	Resets a LAN adapter. An adapter must be reset before any other NCB command that specifies the same number in the ncb_lana_num member will be accepted.
	The IBM NetBIOS 3.0 specification documents several NCB_RESET NCB's. Win32 implements the NCB.RESET using the dynamic link routine interface. Particular values can be passed in specific bytes of the NCB, more specifically:
	• If ncb_lsn is not 0x00, all resources associated with ncb_lana_num are to be freed.
	• If ncb_lsn is 0x00, all resources associated with ncb_lana_num are to be freed, and new resources are to be allocated. The ncb_callname[0] byte specifies the maximum number of sessions, and the ncb_callname[2] byte specifies the maximum number of names. A nonzero value for the ncb_callname[3] byte requests that the application use NAME_NUMBER_1.
NCBSEND	Sends data to the specified session partner. For Windows NT, this is equivalent to the NCBSENDNA command.
NCBSENDNA	Sends data to specified session partner and does not wait for an acknowledgment. For Windows NT, this is equivalent to the NCBSEND command.
NCBSSTAT	Retrieves the status of the session. When this value is specified, the ncb_buffer member points to a buffer to be filled with a SESSION_HEADER structure, followed by one or more SESSION_BUFFER structures.
NCBTRACE	Activates or deactivates NCB tracing. Support for this command in the system is optional and system-specific.
NCBUNLINK	Unlinks the adapter.
ncb_retcode

Specifies the return code. This value is set to NRC_PENDING while an asynchronous operation is in progress. One of the following return code values can be specified:

Value	Meaning
NRC_GOODRET	The operation succeeded.
NRC_BUFLEN	An illegal buffer length was supplied.
NRC_ILLCMD	An illegal command was supplied.
NRC_CMDTMO	The command was timed out.
NRC_INCOMP	The message was incomplete. The application is to issue another command.
NRC_BADDR	The buffer address was illegal.
NRC_SNUMOUT	The session number was out of range.
NRC_NORES	No resource was available.
NRC_SCLOSED	The session was closed.
NRC_CMDCAN	The command was canceled.
NRC_DUPNAME	A duplicate name existed in the local name table.
NRC_NAMTFUL	The name table was full.
NRC_ACTSES	The command finished; the name has active sessions and is no longer registered.
NRC_LOCTFUL	The local session table was full.
NRC_REMTFUL	The remote session table was full. The request to open a session was rejected.
NRC_ILLNN	An illegal name number was specified.
NRC_NOCALL	The system did not find the name that was called.
NRC_NOWILD	Wildcards are not permitted in the ncb_name member.
NRC_INUSE	The name was already in use on the remote adapter.
NRC_NAMERR	The name was deleted.
NRC_SABORT	The session ended abnormally.
NRC_NAMCONF	A name conflict was detected.
NRC_IFBUSY	The interface was busy.
NRC_TOOMANY	Too many commands were outstanding; the application can retry the command later.
NRC_BRIDGE	The ncb_lana_num member did not specify a valid network number.
NRC_CANOCCR	The command finished while a cancel operation was occurring.
NRC_CANCEL	The NCBCANCEL command was not valid; the command was not canceled.
NRC_DUPENV	The name was defined by another local process.
NRC_ENVNOTDEF	The environment was not defined. A reset command must be issued.
NRC_OSRESNOTAV	Operating system resources were exhausted. The application can retry the command later.
NRC_MAXAPPS	The maximum number of applications was exceeded.
NRC_NOSAPS	No service access points (SAPs) were available for NetBIOS.
NRC_NORESOURCES	The requested resources were not available.
NRC_INVADDRESS	The NCB address was not valid.
	This return code is not part of the IBM NetBIOS 3.0 specification and is not returned in the NCB structure. Instead, it is returned by the Netbios function.
NRC_INVDDID	The NCB DDID was invalid.
NRC_LOCKFAIL	The attempt to lock the user area failed.
NRC_OPENERR	An error occurred during an open operation being performed by the device driver. This return code is not part of the IBM NetBIOS 3.0 specification.
NRC_SYSTEM	A system error occurred.
NRC_PENDING	An asynchronous operation is not yet finished.
ncb_lsn

Specifies the local session number. This number uniquely identifies a session within an environment.

ncb_num

Specifies the number of our network name.

ncb_buffer

Points to the message buffer.

ncb_length

Specifies the size, in bytes, of the message buffer.

ncb_callname

Specifies the string that contains the remote name. Trailing space characters should be supplied to make the length of the string equal to NCBNAMSZ.

ncb_name

Specifies the string that contains the local name. Trailing space characters should be supplied to make the length of the string equal to NCBNAMSZ.

ncb_rto

Specifies the receive time-out period, in 500-millisecond units, for the session. A value of zero implies no time-out. Specified only for NCBRECV commands.

ncb_sto

Specifies the send time-out period, in 500-millisecond units, for the session. A value of zero implies no time-out. Specified 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; must be zero.

ncb_event

Specifies a handle to a Windows event that is set to the signaled state when the asynchronous network control block finishes. The event is signaled if the Netbios function returns a nonzero value.

The ncb_event member must be zero if the ncb_command member does not have the ASYNCH value set or if ncb_post is non zero. Otherwise, NRC_ILLCMD is returned.

The event specified by ncb_event is set to the nonsignaled state by the system when an asynchronous NetBIOS command is accepted, and it is set to the signaled state when the asynchronous NetBIOS command finishes.

Using ncb_event to submit asynchronous requests requires fewer system resources than using ncb_post. Also, when ncb_event is nonzero, the pending request is canceled if the thread terminates before the request is processed. This is not true for requests sent by using ncb_post.

Only manual reset events should be used with Netbios. A given event should not be associated with more than one active asynchronous NetBIOS command.

See Also

ACTION_HEADER, ADAPTER_STATUS, FIND_NAME_BUFFER, FIND_NAME_HEADER, LANA_ENUM, NAME_BUFFER, Netbios, SESSION_BUFFER, SESSION_HEADER,


NCCALCSIZE_PARAMS

typedef struct _NCCALCSIZE_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.

Members

rgrc

Specifies an array of rectangles. The first contains the new coordinates of a window that has been moved or resized. The second contains the coordinates of the window before it was moved or resized. The third contains the coordinates of the window's client area before the window was moved or resized. If the window is a child window, the coordinates are relative to the client area of the parent window. If the window is a top-level window, the coordinates are relative to the screen origin.

lppos

Points to a WINDOWPOS structure that contains the size and position values specified in the operation that moved or resized the window.

See Also

MoveWindow, RECT, SetWindowPos, WINDOWPOS, WM_NCCALCSIZE


NDDESHAREINFO

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 gets and sets DDE share attributes maintained by the NetDDE Share Database Manager (DSDM). The security descriptor associated with each DDE share is not passed through this structure but is accessed through specific functions. The NetDDE DSDM API accepts this structure for set functions; for get functions, the DSDM returns the structure packed into the supplied buffer along with the data referenced by the members lpszShareName, lpszAppTopicList, and lpszItemList.

Members

lRevision

Specifies the revision level of the NDDESHAREINFO structure. Currently, the revision level is 1.

lpszShareName

Points to a buffer containing a null-terminated string that specifies the name of the share. This string must be no more than MAX_NDDESHARENAME characters long.

lShareType

Specifies the DDE share type(s). A DDE share can assume more than one type. This member can be a combination of the following supported DDE share types:

Share type	Meaning
SHARE_TYPE_OLD	Specifies that the share contains a DDE application/topic pair.
SHARE_TYPE_NEW	Specifies that the share contains an OLE application/topic pair.
SHARE_TYPE_STATIC	Specifies that the share contains a static application/topic pair.
lpszAppTopicList

Points to a buffer containing null-terminated strings for the DDE, OLE, and static application/topic pairs. The buffer should be in the following format:

    <DDE application name>|<DDE topic name>\0

        <OLE application name>|<OLE topic name>\0

        <static application name>|<static topic name>\0\0

fSharedFlag

Specifies whether the share is accessible to remote clients for linking. If this flag is set to FALSE, the DDE share will not allow remote users to communicate through it by using DDE. However, local users can still communicate through the DDE share. Local client links are always implied if the associated DACL grants access.

fService

If this flag is set, the DDE share will not check whether the current user has set it as trusted before before allowing DDE communication through it.

fStartAppFlag

If this flag is set and the share is trusted to start applications, NetDDE will attempt to start the application specified by lpszAppTopicList if it cannot initially start a DDE conversation with the application.

nCmdShow

When NetDDE starts an application to initiate a DDE conversation with it, this value is sent to the application by the nCmdShow parameter of the WinMain function. It defines the preferred mode for the application window to be shown in. This parameter is significant only if fStartAppFlag is active. The logged on user in whose context the application is started can also override this option when promoting the share to trusted status. The default for this 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 by a NDdeShareSetInfo or NDdeSetShareSecurity call, these values are changed.

cNumItems

Specifies the number of items listed in lpszItemList. If cNumItems is zero, then lpszItemList is empty, and the share information and associated security descriptor apply to all items serviced by the associated application.

lpszItemList

Points to a buffer containing null-terminated strings that specify the items the client application in a DDE transaction can request or start advise loops on. If no items are listed, the DDE share allows any item to be used. The number of items in the list must match the cNumItems count.

See Also

NDdeSetShareSecurity, NDdeShareSetInfo, WinMain


NETRESOURCE

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.

Members

dwScope

Specifies the scope of the enumeration. Currently, this member can be one of the following values:

Value	Meaning
RESOURCE_CONNECTED	Currently connected resources (the dwUsage member is undefined).
RESOURCE_GLOBALNET	Resources on the network.
RESOURCE_REMEMBERED	Remembered (persistent) connections (dwUsage is undefined).
dwType

Specifies a bitmask that gives the resource type. Currently, this member can be one of the following values:

Value	Meaning
RESOURCETYPE_ANY	All resources
RESOURCETYPE_DISK	Disk resources
RESOURCETYPE_PRINT	Print resources
dwDisplayType

Specifies how the network object should be displayed in a network browsing user interface. Currently, this member can be the following values:

Value	Meaning
RESOURCEDISPLAYTYPE_DOMAIN
	The object should be displayed as a domain.
RESOURCEDISPLAYTYPE_GENERIC
	The method used to display the object does not matter.
RESOURCEDISPLAYTYPE_SERVER
	The object should be displayed as a server.
RESOURCEDISPLAYTYPE_SHARE
	The object should be displayed as a sharepoint.
dwUsage

Specifies a bitmask that gives the resource usage. This member is defined only if dwScope is RESOURCE_GLOBALNET. Currently, this member can be one of the following values:

Value	Meaning
RESOURCEUSAGE_CONNECTABLE	This is a connectable resource; the name pointed to by the lpRemoteName member can be passed to the WNetAddConnection function to make a network connection.
RESOURCEUSAGE_CONTAINER	This is a container resource; the name pointed to by the lpRemoteName member can be passed to the WNetOpenEnum function to enumerate the resources in the container.
lpLocalName

Points to the name of a local device if the dwScope member is RESOURCE_CONNECTED or RESOURCE_REMEMBERED. This member is NULL if the connection does not use a device. Otherwise, it is undefined.

lpRemoteName

Points to a remote network name if the entry is a network resource.

If the entry is a current or persistent connection, lpRemoteName points to the network name associated with the name pointed to by the lpLocalName member.

lpComment

Points to a provider-supplied comment.

lpProvider

Points to the name of the provider owning this resource. This member can be NULL if the provider name is unknown.

See Also

WNetAddConnection, WNetCloseEnum, WNetEnumResource, WNetOpenEnum


NEWCPLINFO

typedef struct tagNEWCPLINFO {  // ncpli

    DWORD dwSize;

    DWORD dwFlags;

    DWORD dwHelpContext;

    LONG  lData;

    HICON hIcon;

    TCHAR  szName[32];

    TCHAR  szInfo[64];

    TCHAR  szHelpFile[128];

} NEWCPLINFO;

The NEWCPLINFO structure contains resource information and a user-defined value for a dialog box supported by a Control Panel application.

Members

dwSize

Specifies the length of the structure, in bytes.

dwFlags

Specifies Control Panel flags.

dwHelpContext

Specifies the context number of a topic in a Help (.HLP) file. This topic is intended to be displayed when the user selects help for the dialog box.

lData

Specifies data defined by the application.

hIcon

Identifies the icon that represents the dialog box. This icon is intended to be displayed by the application that controls the Control Panel application.

szName

Specifies a null-terminated string that contains the dialog box name. The name is intended to be displayed below the icon.

szInfo

Specifies a null-terminated string containing the dialog box description. The description is intended to be displayed when the icon for the dialog box is selected.

szHelpFile

Specifies a null-terminated string that contains the path of the help file, if any, for the application.

See Also

CPLINFO, CPL_NEWINQUIRE


NEWTEXTMETRIC

typedef struct tagNEWTEXTMETRIC { // ntm

    LONG   tmHeight;

    LONG   tmAscent;

    LONG   tmDescent;

    LONG   tmInternalLeading;

    LONG   tmExternalLeading;

    LONG   tmAveCharWidth;

    LONG   tmMaxCharWidth;

    LONG   tmWeight;

    LONG   tmOverhang;

    LONG   tmDigitizedAspectX;

    LONG   tmDigitizedAspectY;

    BCHAR  tmFirstChar;

    BCHAR  tmLastChar;

    BCHAR  tmDefaultChar;

    BCHAR  tmBreakChar;

    BYTE   tmItalic;

    BYTE   tmUnderlined;

    BYTE   tmStruckOut;

    BYTE   tmPitchAndFamily;

    BYTE   tmCharSet;

    DWORD  ntmFlags;

    UINT   ntmSizeEM;

    UINT   ntmCellHeight;

    UINT   ntmAvgWidth;

} NEWTEXTMETRIC;

The NEWTEXTMETRIC structure contains data that describes a physical font.

Members

tmHeight

Specifies the height (ascent + descent) of characters.

tmAscent

Specifies the ascent (units above the base line) of characters.

tmDescent

Specifies the descent (units below the base line) of characters.

tmInternalLeading

Specifies the amount of leading (space) inside the bounds set by the tmHeight member. Accent marks and other diacritical characters may occur in this area. The designer may set this member to zero.

tmExternalLeading

Specifies the amount of extra leading (space) that the application adds between rows. Since this area is outside the font, it contains no marks and is not altered by text output calls in either OPAQUE or TRANSPARENT mode. The designer may set this member to zero.

tmAveCharWidth

Specifies the average width of characters in the font (generally defined as the width of the letter x). This value does not include overhang required for bold or italic characters.

tmMaxCharWidth

Specifies the width of the widest character in the font.

tmWeight

Specifies the weight of the font.

tmOverhang

Specifies the extra width per string that may be added to some synthesized fonts. When synthesizing some attributes, such as bold or italic, graphics device interface (GDI) or a device may have to add width to a string on both a per-character and per-string basis. For example, GDI makes a string bold by expanding the spacing of each character and overstriking by an offset value; it italicizes a font by shearing the string. In either case, there is an overhang past the basic string. For bold strings, the overhang is the distance by which the overstrike is offset. For italic strings, the overhang is the amount the top of the font is sheared past the bottom of the font.

The tmOverhang member enables the application to determine how much of the character width returned by a GetTextExtentPoint32 function call on a single character is the actual character width and how much is the per-string extra width. The actual width is the extent minus the overhang.

tmDigitizedAspectX

Specifies the horizontal aspect of the device for which the font was designed.

tmDigitizedAspectY

Specifies the vertical aspect of the device for which the font was designed. The ratio of the tmDigitizedAspectX and tmDigitizedAspectY members is the aspect ratio of the device for which the font was designed.

tmFirstChar

Specifies the value of the first character defined in the font.

tmLastChar

Specifies the value of the last character defined in the font.

tmDefaultChar

Specifies the value of the character to be substituted for characters that are not in the font.

tmBreakChar

Specifies the value of the character to be used to define word breaks for text justification.

tmItalic

Specifies an italic font if it is nonzero.

tmUnderlined

Specifies an underlined font if it is nonzero.

tmStruckOut

Specifies a strikeout font if it is nonzero.

tmPitchAndFamily

Specifies the pitch and family of the selected font. The low-order bit (bit 0) specifies the pitch of the font. If it is 1, the font is variable pitch (or proportional). If it is 0, the font is fixed pitch (or monospace). Bits 1 and 2 specify the font type. If both bits are 0, the font is a raster font; if bit 1 is 1 and bit 2 is 0, the font is a vector font; if bit 1 is 0 and bit 2 is set, or if both bits are 1, the font is some other type. Bit 3 is 1 if the font is a device font; otherwise, it is 0.

The four high-order bits designate the font family. The tmPitchAndFamily member can be combined with the hexadecimal value 0xF0 by using the bitwise AND operator and can then be compared with the font family names for an identical match. For more information about the font families, see the LOGFONT structure.

tmCharSet

Specifies the character set of the font.

ntmFlags

Specifies whether the font is italic, underscored, outlined, bold, and so forth. The following list shows the bits corresponding to each font type:

Bit	Meaning
0	Italic
1	Underscore
2	Negative
3	Outline
4	Strikeout
5	Bold
ntmSizeEM

Specifies the size of the em square for the font. This value is in "notional units" (that is, the units for which the font was designed).

ntmCellHeight

Specifies the height, in notional units, of the font. This value should be compared with the value of the ntmSizeEM member.

ntmAvgWidth

Specifies the average width of characters in the font, in notional units. This value should be compared with the value of the ntmSizeEM member.

Remarks

The last four members of the NEWTEXTMETRIC structure are not included in the TEXTMETRIC structure; in all other respects, the structures are identical.

The sizes in the NEWTEXTMETRIC structure are typically given in logical units; that is, they depend on the current mapping mode of the display context.

See Also

EnumFontFamilies, GetTextExtentPoint32, GetTextMetrics, LOGFONT


NEWTEXTMETRICEX  (preliminaryWindows 95)
NEWTEXTMETRICEX  (preliminary−Windows 95)

typedef struct tagNEWTEXTMETRICEX {
    NEWTEXTMETRIC  ntmentm;
    FONTSIGNATURE  ntmeFontSignature;
} NEWTEXTMETRICEX;

The NEWTEXTMETRICEX structure contains information about a physical font.

Members

ntmentm

Specifies a NEWTEXTMETRIC structure.

ntmeFontSignature

Specifies a FONTSIGNATURE structure indicating the coverage of the font.

See Also

NEWTEXTMETRIC


NM_LISTVIEW  (preliminaryWindows NT)
NM_LISTVIEW  (preliminary−Windows NT)

typedef struct tagNM_LISTVIEW {

    NMHDR hdr;

    int   iItem;

    int   iSubItem;

    UINT  uNewState;

    UINT  uOldState;

    UINT  uChanged;

    POINT ptAction;

    LPARAM lParam;

} NM_LISTVIEW;

The NM_LISTVIEW structure contains information about a list view notification message.

Members

hdr

Required for all WM_NOTIFY messages.

iItem

List view item, or −1 if not used.

iSubItem

Subitem, or zero if none.

uNewState

New item state. This member is zero for notification messages that do not use it.

uOldState

Old item state. This member is zero for notification messages that do not use it.

uChanged

Item attributes that have changed. This member is zero for notifications that do not use it. Otherwise, it can have the same values as the mask member of the LV_ITEM structure.

ptAction

Location at which the event occurred. This member is valid only for the LVN_BEGINDRAG and LVN_BEGINRDRAG notification messages.

Remarks

The address of the NM_LISTVIEW structure is specified as the lParam parameter of the WM_NOTIFY message for several list view notification messages.

See Also

LV_ITEM, LVN_BEGINDRAG, LVN_BEGINRDRAG, WM_NOTIFY


NM_TREEVIEW  (preliminaryWindows NT)
NM_TREEVIEW  (preliminary−Windows NT)

typedef struct _NM_TREEVIEW {  nmtv

    NMHDR    hdr;

    UINT     action;        TV_ITEM  itemOld;   // see below

    TV_ITEM  itemNew;

    POINT    ptDrag;

} NM_TREEVIEW;

typedef NM_TREEVIEW FAR *LPNM_TREEVIEW;

The NM_TREEVIEW structure contains information about a tree view notification message.

Members

hdr

Required for all WM_NOTIFY messages.

action

Notification-specific action flag.

itemOld

Address of TV_ITEM structures that contain information about the old item state. This member is zero for notification messages that do not use it.

itemNew

Address of TV_ITEM structures that contain information about the new item state. This member is zero for notification messages that do not use it.

ptDrag

POINT structure that contains the client coordinates of the mouse at the time the event occurred that caused the notification message to be sent.

Remarks

The address of this structure is specified as the lParam parameter of the WM_NOTIFY message for several tree-view notification messages.

See Also

POINT, TV_ITEM, WM_NOTIFY


NM_UPDOWN  (preliminaryWindows NT)
NM_UPDOWN  (preliminary−Windows NT)

typedef struct _NM_UPDOWN {  nmud

    NMHDR    hdr;       // notification message header

    int     iPos;        // current position

    int  iDelta;      // proposed change in position

} NM_UPDOWNW;

The NM_UPDOWN structure contains information about an up-down control notification message.

Members

hdr

Notification message header structure. This is required for all WM_NOTIFY messages.

iPos

Signed integer value that is the current position of the up-down control.

iDelta

Signed integer value that is the proposed change in the position of the up-down control.

Remarks

The address of this structure is specified as the lParam parameter of the WM_NOTIFY message for the UDN_DELTAPOS notification message.

See Also

NMHDR, UDN_DELTAPOS, WM_NOTIFY


NMHDR  (preliminaryWindows NT)
NMHDR  (preliminary−Windows NT)

typedef struct tagNMHDR {

    HWND hwndFrom;

    UINT idFrom;

    UINT code;

} NMHDR;

The NMHDR structure contains information about a notification message. The pointer to this structure is specified as the lParam member of the WM_NOTIFY message.

Members

hwndFrom

Handle to control sending message

idFrom

Identifier of control sending message

code

Notification code. This member can be a control-specific notification code, or it can be one of the following common notification values:

Value	Meaning
NM_CLICK	The user has clicked the left mouse button within the control.
NM_DBLCLK	The user has double-clicked the left mouse button within the control.
NM_KILLFOCUS	The control has lost the input focus.
NM_OUTOFMEMORY	The control could not complete an operation because there was not enough memory available.
NM_RCLICK	The user has clicked the right mouse button within the control.
NM_RDBLCLK	The user has double-clicked the right mouse button within the control.
NM_RETURN	The control has the input focus, and the user has pressed the ENTER key.
NM_SETFOCUS	The control has received the input focus.


NONCLIENTMETRICS

typedef struct tagNONCLIENTMETRICS {

    UINT    cbSize;

    int     iBorderWidth;

    int     iScrollWidth;

    int     iScrollHeight;

    int     iCaptionWidth;

    int     iCaptionHeight;

    LOGFONT lfCaptionFont;

    int     iSmCaptionWidth;

    int     iSmCaptionHeight;

    LOGFONT lfSmCaptionFont;

    int     iMenuWidth;

    int     iMenuHeight;

    LOGFONT lfMenuFont;

    LOGFONT lfStatusFont;

    LOGFONT lfMessageFont;

} NONCLIENTMETRICS, FAR* LPNONCLIENTMETRICS;

The NONCLIENTMETRICS structure contains the scalable metrics associated with the nonclient area of a nonminimized window. This structure is used by the SPI_GETNONCLIENTMETRICS and SPI_SETNONCLIENTMETRICS actions of SystemParametersInfo.

Members

cbSize

Specifies the size of the structure, in bytes.

iBorderWidth

Specifies the thickness, in pixels, of the sizing border.

iScrollWidth

Specifies the width, in pixels, of a standard vertical scroll bar.

iScrollHeight

Specifies the height, in pixels, of a standard horizontal scroll bar.

iCaptionWidth

Specifies the width, in pixels, of caption buttons.

iCaptionHeight

Specifies the height, in pixels, of caption buttons.

lfCaptionFont

Contains information about the caption font.

iSmCaptionWidth

Specifies the width, in pixels, of small caption buttons.

iSmCaptionHeight

Specifies the height, in pixels, of small captions.

iMenuWidth

Specifies the width, in pixels, of menu-bar buttons.

iMenuHeight

Specifies the height, in pixels, of a menu bar.

lfMenuFont

Contains information about the font used in menu bars.

lfStatusFont

Contains information about the font used in status bars.

lfMessageFont

Contains information about the font used in message boxes.

See Also

SystemParametersInfo


NS_SERVICE_INFO

typedef struct _NS_SERVICE_INFO {

    DWORD   dwNameSpace;

    SERVICE_INFO ServiceInfo;

} NS_SERVICE_INFO;

The NS_SERVICE_INFO structure contains information about a network service or a network service type in the context of a specified name space, or a set of default name spaces.

Members

dwNameSpace

Specifies the name space or a set of default name spaces to which this service information applies.

Use one of the following constant values to specify a name space:

Value	Name Space
NS_DEFAULT	A set of default name spaces. The set of default name spaces typically includes all the name spaces installed on the system. System administrators, however, can exclude particular name spaces from the set.
NS_DNS	The Domain Name System used in the Internet to resolve the name of the host.
NS_MS
NS_NDS	The NetWare 4 provider.
NS_NETBT	The NetBIOS over TCP/IP layer. The operating system registers their computer names with NetBIOS. This name space is used to convert a computer name to an IP address that uses this registration.
NS_NIS
NS_SAP	The NetWare Service Advertising Protocol. This can access the Netware bindery, if appropriate. NS_SAP is a dynamic name space that enables the registration of services.
NS_STDA
NS_TCPIP_HOSTS	Lookup value in the <systemroot>\system32\drivers\etc\posts file.
NS_TCPIP_LOCAL	Local TCP/IP name resolution mechanisms, including comparisons against the local host name and lookup value in the cache of host to IP address mappings.
NS_WINS
NS_X500
ServiceInfo

A SERVICE_INFO structure that contains information about a network service or network service type.

See Also

GetService, SetService, SERVICE_INFO


NUMBERFMT

typedef struct _numberfmt {

    UINT      NumDigits;

    UINT      LeadingZero;

    UINT      Grouping;

    LPTSTR    lpDecimalSep;

    LPTSTR    lpThousandSep;

    UINT      NegativeOrder;

} NUMBERFMT;

The NUMBERFMT structure contains information that defines the format of a number string. The GetNumberFormat function uses this information to customize a number string for a specified locale.

Members

NumDigits

Specifies the number of fractional digits. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_IDIGITS.

LeadingZero

Specifies whether to use leading zeroes in decimal fields. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_ILZERO.

Grouping

Specifies the size of each group of digits to the left of the decimal. Values in the range 0 − 9 are valid.

lpDecimalSep

Points to a null-terminated decimal separator string.

lpThousandSep

Points to a null-terminated thousand separator string.

NegativeOrder

Specifies the negative number mode. This is equivalent to the locale information specified by the LCTYPE constant value LOCALE_INEGNUMBER.

See Also

GetNumberFormat


OFSTRUCT

typedef struct _OFSTRUCT { // of

    BYTE cBytes;

    BYTE fFixedDisk;

    WORD nErrCode;

    WORD Reserved1;

    WORD Reserved2;

    CHAR szPathName[OFS_MAXPATHNAME];

} OFSTRUCT;

The OFSTRUCT structure contains information about a file that the OpenFile function opened or attempted to open.

Members

cBytes

Specifies the length, in bytes, of the structure.

fFixedDisk

Specifies whether the file is on a hard (fixed) disk. This member is nonzero if the file is on a hard disk.

nErrCode

Specifies the MS-DOS error code if the OpenFile function failed.

Reserved1

Reserved; do not use.

Reserved2

Reserved; do not use.

szPathName

Specifies the path and filename of the file. This string consists of characters from the Windows character set.

See Also

OpenFile


OPENFILENAME

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.

Members

lStructSize

Specifies the length, in bytes, of the structure.

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

hInstance

Identifies a data block that contains a dialog box template specified by the lpTemplateName 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"), and 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 member 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 member is NULL, the dialog box lists but does not save user-defined filter strings.

Windows 95: If this member is not NULL, the value of the nMaxCustFilter member is used to determine the length of the corresponding string.

nMaxCustFilter

Specifies the size, in characters, of the buffer identified by lpstrCustomFilter. This buffer should be at least 40 characters long. This member is ignored if lpstrCustomFilter is NULL or points to a NULL string.

nFilterIndex

Specifies an index into the buffer pointed to by lpstrFilter. The 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 nFilterIndex is zero, the custom filter is used. If nFilterIndex is zero and lpstrCustomFilter is NULL, the system uses the first filter in the buffer identified by lpstrFilter. If all three members are zero or NULL, the system does not use any filters and does not show any files in the file list control of the dialog box.

lpstrFile

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 lpstrFile. The GetOpenFileName and GetSaveFileName functions return FALSE if the buffer is too small to contain the file information. The buffer should be at least 256 characters long. This member is ignored if lpstrFile 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. The 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 flags:

Flag	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 definition of the File Name list box must contain the LBS_EXTENDEDSEL value.) Specifies that the File Name list box allows multiple selections.  If the dialog box is created by using a private template, the  definition of the File Name list box must contain the LBS_EXTENDEDSEL value. When this flag is set, the lpstrFile member points to a buffer containing the path to the current directory and all filenames in the selection. The first filename is separated from the path by a space. Each subsequent filename is separated by one space from the preceding filename. Note that for the new Explorer-style dialogs (dialogs that have the OFN_EXPLORER flag set), a single null character, \0, separates the filenames, and two null characters, \0\0, terminate the entire string.
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 uses 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 hInstance and lpTemplateName.
OFN_ENABLETEMPLATEHANDLE
	Indicates that hInstance identifies a data block that contains a preloaded dialog box template. The operating system ignores lpTemplateName if this flag is specified.
OFN_EXTENSIONDIFFERENT
	Specifies that the user typed a filename extension that differs from the extension specified by lpstrDefExt. The function does not use this flag if lpstrDefExt is NULL.
OFN_FILEMUSTEXIST
	Specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box. If this flag is specified, the OFN_PATHMUSTEXIST flag is also used.
OFN_HIDEREADONLY
	Hides the Read Only check box.
OFN_NOCHANGEDIR
	Causes the dialog box to set the current directory back to what it was when the dialog box was called.
OFN_NOLONGNAMES
	Specifies that long filenames are not displayed in the File Name list box.
OFN_NONETWORKBUTTON
	Hides and disables the Network button.
OFN_NOREADONLYRETURN
	Specifies that the returned file does not have the Read Only check box checked and is not in a write-protected directory.
OFN_NOTESTFILECREATE
	Specifies that the file is not created before the dialog box is closed. This flag should be specified if the application saves the file on a create-nonmodify network sharepoint. When an application specifies this flag, the library does not check for write protection, a full disk, an open drive door, or network protection. Applications using this flag must perform file operations carefully, because a file cannot be reopened once it is closed.
OFN_NOVALIDATE
	Specifies that the common dialog boxes allow invalid characters in the returned filename. Typically, the calling application uses a hook function that checks the filename by using the FILEOKSTRING message. If the text box in the edit control is empty or contains nothing but spaces, the lists of files and directories are updated. If the text box in the edit control contains anything else, nFileOffset and nFileExtension are set to values generated by parsing the text. No default extension is added to the text, nor is text copied to the buffer specified by lpstrFileTitle.
	If the value specified by nFileOffset is less than zero, the filename is invalid. Otherwise, the filename is valid, and nFileExtension and nFileOffset can be used as if the OFN_NOVALIDATE flag had not been specified.
OFN_OVERWRITEPROMPT
	Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.
OFN_PATHMUSTEXIST
	Specifies that the user can type only valid paths and filenames. If this flag is used and the user types an invalid path and filename in the File Name entry field, the dialog box function displays a warning in a message box.
OFN_READONLY
	Causes the Read Only check box to be checked initially when the dialog box is created. This flag indicates the state of the Read Only check box when the dialog box is closed.
OFN_SHAREAWARE
	Specifies that if a call to the OpenFile function fails because of a network sharing violation, the error is ignored and the dialog box returns the given filename. If this flag is not specified, 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 flags:
Flag	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 pointed to by lpstrFile. 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 lpstrFile. For example, if lpstrFile points to the following string, "c:\dir1\dir2\file.ext", this member contains the value 18. If the user did not type an extension and lpstrDefExt is NULL, this member specifies an offset to the terminating null character. If the user typed "." as the last character in the filename, this member specifies 0.

lpstrDefExt

Points to a buffer that contains the default extension. GetOpenFileName and GetSaveFileName append this extension to the filename if the user fails to type an extension. This string can be any length, but only the first three characters are appended. The string should not contain a period (.). If this member is NULL and the user fails to type an extension, no extension is appended.

lCustData

Specifies application-defined data that the operating system passes to the hook function identified by lpfnHook. 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.

lpTemplateName

Points to a null-terminated string that names the dialog box template to be substituted for the standard dialog box template. An application can use the MAKEINTRESOURCE macro for numbered dialog box resources. This member is only used if Flags specifies the OFN_ENABLETEMPLATE flag; otherwise, this member is ignored.

See Also

GetOpenFileName, GetSaveFileName


OSVERSIONINFO

typedef struct _OSVERSIONINFO{

    DWORD dwOSVersionInfoSize;

    DWORD dwMajorVersion;

    DWORD dwMinorVersion;

    DWORD dwBuildNumber;

    DWORD dwPlatformId;

    TCHAR szCSDVersion[ 128 ];

} OSVERSIONINFO;

The OSVERSIONINFO data structure contains operating system version information. The information includes major and minor version numbers, a build number, a platform identifier, and descriptive text about the operating system. This structure is used with the GetVersionEx function.

Members

dwOSVersionInfoSize

Specifies the size, in bytes, of this data structure. Set this member to sizeof(OSVERSIONINFO) before calling the GetVersionEx function.

dwMajorVersion

Identifies the major version number of the operating system. For example, the major version number of the Daytona release of Windows NT is 3.

dwMinorVersion

Identifies the minor version number of the operating system. For example, the minor version number of the Daytona release of Windows NT is 5.

dwBuildNumber

Identifies the build number of the operating system. For example, the build number of the July 1993 release of Windows NT is 512.

dwPlatformId

Identifies the platform supported by the operating system.

This member can have one of the following values:

Value	Platform
VER_PLATFORM_WIN32s	Win32s on Windows 3.1
VER_PLATFORM_WIN32_WINDOWS	Win32 on Windows 95
VER_PLATFORM_WIN32_NT	Windows NT
szCSDVersion

Contains a zero-terminated string that provides arbitrary additional information about the operating system.

See Also

GetVersionEx


OUTLINETEXTMETRIC

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.

Members

otmSize

Specifies the size, in bytes, of the OUTLINETEXTMETRIC structure.

otmTextMetrics

Specifies a TEXTMETRIC structure containing further information about the font.

otmFiller

Specifies a value that causes the structure to be byte aligned.

otmPanoseNumber

Specifies the PANOSE number for this font.

otmfsSelection

Specifies the nature of the font pattern. This member can be a combination of the following bits:

Bit	Meaning
0	Italic
1	Underscore
2	Negative
3	Outline
4	Strikeout
5	Bold
otmfsType

Specifies whether the font is licensed. Licensed fonts must not be modified or exchanged. If bit 1 is set, the font may not be embedded in a document. If bit 1 is clear, the font can be embedded. If bit 2 is set, the embedding is read-only.

otmsCharSlopeRise

Specifies the slope of the cursor. This value is 1 if the slope is vertical. Applications can use this value and the value of the otmsCharSlopeRun member to create an italic cursor that has the same slope as the main italic angle (specified by the otmItalicAngle member).

otmsCharSlopeRun

Specifies the slope of the cursor. This value is zero if the slope is vertical. Applications can use this value and the value of the otmsCharSlopeRise member to create an italic cursor that has the same slope as the main italic angle (specified by the otmItalicAngle member).

otmItalicAngle

Specifies the main italic angle of the font, in tenths of a degree counterclockwise from vertical. Regular (roman) fonts have a value of zero. Italic fonts typically have a negative italic angle (that is, they lean to the right).

otmEMSquare

Specifies the number of logical units defining the x- or y-dimension of the em square for this font. (The number of units in the x- and y-directions are always the same for an em square.)

otmAscent

Specifies the maximum distance characters in this font extend above the base line. This is the typographic ascent for the font.

otmDescent

Specifies the maximum distance characters in this font extend below the base line. This is the typographic descent for the font.

otmLineGap

Specifies typographic line spacing.

otmsCapEmHeight

Not supported.

otmsXHeight

Not supported.

otmrcFontBox

Specifies the bounding box for the font.

otmMacAscent

Specifies the maximum distance characters in this font extend above the base line for the Macintosh® computer.

otmMacDescent

Specifies the maximum distance characters in this font extend below the base line for the Macintosh® computer.

otmMacLineGap

Specifies line-spacing information for the Macintosh® computer.

otmusMinimumPPEM

Specifies the smallest recommended size for this font, in pixels per em-square.

otmptSubscriptSize

Specifies the recommended horizontal and vertical size for subscripts in this font.

otmptSubscriptOffset

Specifies the recommended horizontal and vertical offset for subscripts in this font. The subscript offset is measured from the character origin to the origin of the subscript character.

otmptSuperscriptSize

Specifies the recommended horizontal and vertical size for superscripts in this font.

otmptSuperscriptOffset

Specifies the recommended horizontal and vertical offset for superscripts in this font. The superscript offset is measured from the character base line to the base line of the superscript character.

otmsStrikeoutSize

Specifies the width of the strikeout stroke for this font. Typically, this is the width of the em dash for the font.

otmsStrikeoutPosition

Specifies the position of the strikeout stroke relative to the base line for this font. Positive values are above the base line and negative values are below.

otmsUnderscoreSize

Specifies the thickness of the underscore character for this font.

otmsUnderscorePosition

Specifies the position of the underscore character for this font.

otmpFamilyName

Specifies the offset from the beginning of the structure to a string specifying the family name for the font.

otmpFaceName

Specifies the offset from the beginning of the structure to a string specifying the typeface name for the font. (This typeface name corresponds to the name specified in the LOGFONT structure.)

otmpStyleName

Specifies the offset from the beginning of the structure to a string specifying the style name for the font.

otmpFullName

Specifies the offset from the beginning of the structure to a string specifying the full name for the font. This name is unique for the font and often contains a version number or other identifying information.

Remarks

The sizes returned in OUTLINETEXTMETRIC are given in logical units; that is, they depend on the current mapping mode of the specified display context.

See Also

GetOutlineTextMetrics, LOGFONT, TEXTMETRIC


OUTPUT_DEBUG_STRING_INFO

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.

Members

lpDebugStringData

Points to the address of the debugging string in the calling process's address space. The debugger can use the ReadProcessMemory function to retrieve the value of the string.

fUnicode

Specifies the format of the debugging string. If this member is zero, the debugging string is 8-bit ASCII; if it is nonzero, the string is 16-bit Unicode™.

nDebugStringLength

Specifies the length, in bytes, of the debugging string. The length includes the string's terminating null character.

See Also

DEBUG_EVENT, ReadProcessMemory


OVERLAPPED

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 (I/O).

Members

Internal

Reserved for operating system use. This member, which specifies a system-dependent status, is valid when the GetOverlappedResult function returns without setting the extended error information to ERROR_IO_PENDING.

InternalHigh

Reserved for operating system use. This member, which specifies the length of the data transferred, is valid when the GetOverlappedResult function returns TRUE.

Offset

Specifies a file position at which to start the transfer. The file position is a byte offset from the start of the file. The calling process sets this member before calling the ReadFile or WriteFile function. This member must be set to zero when reading from or writing to named pipes and communications devices.

OffsetHigh

Specifies the high word of the byte offset at which to start the transfer. This member must be set to zero when reading from or writing to named pipes and communications devices.

hEvent

Identifies an event set to the signaled state when the transfer has been completed. The calling process sets this member before calling the ReadFile, WriteFile, ConnectNamedPipe, or TransactNamedPipe function.

Remarks

Under Windows NT 3.5, Offset and OffsetHigh must be set to zero when reading from or writing to named pipes and communications devices. The Win32 documentation of OVERLAPPED for Windows NT 3.1 did not say this; it stated instead that these members were ignored. Developers who are porting NT 3.1 code to NT 3.5 should make sure that their code sets these members to zero as indicated.

See Also

ConnectNamedPipe, CreateFile, GetOverlappedResult, ReadFile, ReadFileEx, TransactNamedPipe, WriteFile, WriteFileEx


PAINTSTRUCT

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.

Members

hdc

Identifies the display DC to be used for painting.

fErase

Specifies whether the background must be erased. This value is nonzero if the application should erase the background. The application is responsible for erasing the background if a window class is created without a background brush. For more information, see the description of the hbrBackground member of the WNDCLASS structure.

rcPaint

Specifies a RECT structure that specifies the upper left and lower right corners of the rectangle in which the painting is requested.

fRestore

Reserved; used internally by Windows.

fIncUpdate

Reserved; used internally by Windows.

rgbReserved

Reserved; used internally by Windows.

See Also

BeginPaint, RECT, WNDCLASS


PALETTEENTRY

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.

Members

peRed

Specifies a red intensity value for the palette entry.

peGreen

Specifies a green intensity value for the palette entry.

peBlue

Specifies a blue intensity value for the palette entry.

peFlags

Specifies how the palette entry is to be used. The peFlags member may be set to NULL or one of the following values:

Value	Meaning
PC_EXPLICIT	Specifies that the low-order word of the logical palette entry designates a hardware palette index. This flag allows the application to show the contents of the display device palette.
PC_NOCOLLAPSE	Specifies that the color be placed in an unused entry in the system palette instead of being matched to an existing color in the system palette. If there are no unused entries in the system palette, the color is matched normally. Once this color is in the system palette, colors in other logical palettes can be matched to this color.
PC_RESERVED	Specifies that the logical palette entry be used for palette animation. This flag prevents other windows from matching colors to the palette entry since the color frequently changes. If an unused system-palette entry is available, the color is placed in that entry. Otherwise, the color is available for animation.
See Also

LOGPALETTE


PANOSE

typedef struct tagPANOSE { // pnse

    BYTE bFamilyType;

    BYTE bSerifStyle;

    BYTE bWeight;

    BYTE bProportion;

    BYTE bContrast;

    BYTE bStrokeVariation;

    BYTE bArmStyle;

    BYTE bLetterform;

    BYTE bMidline;

    BYTE bXHeight;

} PANOSE

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.

Members

bFamilyType

For Latin fonts, bFamilyType can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_FAMILY_TEXT_DISPLAY	Text and display
PAN_FAMILY_SCRIPT	Script
PAN_FAMILY_DECORATIVE	Decorative
PAN_FAMILY_PICTORIAL	Pictorial
bSerifStyle

Specifies the serif style. For Latin fonts, bSerifStyle can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_SERIF_COVE	Cove
PAN_SERIF_OBTUSE_COVE	Obtuse cove
PAN_SERIF_SQUARE_COVE	Square cove
PAN_SERIF_OBTUSE_SQUARE_COVE	Obtuse square cove
PAN_SERIF_SQUARE	Square
PAN_SERIF_THIN	Thin
PAN_SERIF_BONE	Bone
PAN_SERIF_EXAGGERATED	Exaggerated
PAN_SERIF_TRIANGLE	Triangle
PAN_SERIF_NORMAL_SANS	Normal sans serif
PAN_SERIF_OBTUSE_SANS	Obtuse sans serif
PAN_SERIF_PERP_SANS	Perp sans serif
PAN_SERIF_FLARED	Flared
PAN_SERIF_ROUNDED	Rounded
bWeight

For Latin fonts, bWeight can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_WEIGHT_VERY_LIGHT	Very light
PAN_WEIGHT_LIGHT	Light
PAN_WEIGHT_THIN	Thin
PAN_WEIGHT_BOOK	Book
PAN_WEIGHT_MEDIUM	Medium
PAN_WEIGHT_DEMI	Demibold
PAN_WEIGHT_BOLD	Bold
PAN_WEIGHT_HEAVY	Heavy
PAN_WEIGHT_BLACK	Black
PAN_WEIGHT_NORD	Nord
bProportion

For Latin fonts, bProportion can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_PROP_OLD_STYLE	Old style
PAN_PROP_MODERN	Modern
PAN_PROP_EVEN_WIDTH	Even width
PAN_PROP_EXPANDED	Expanded
PAN_PROP_CONDENSED	Condensed
PAN_PROP_VERY_EXPANDED	Very expanded
PAN_PROP_VERY_CONDENSED	Very condensed
PAN_PROP_MONOSPACED	Monospaced
bContrast

For Latin fonts, bContrast can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_CONTRAST_NONE	None
PAN_CONTRAST_VERY_LOW	Very low
PAN_CONTRAST_LOW	Low
PAN_CONTRAST_MEDIUM_LOW	Medium low
PAN_CONTRAST_MEDIUM	Medium
PAN_CONTRAST_MEDIUM_HIGH	Medium high
PAN_CONTRAST_HIGH	High
PAN_CONTRAST_VERY_HIGH	Very high
bStrokeVariation

For Latin fonts, bStrokeVariation can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_STROKE_GRADUAL_DIAG	Gradual/diagonal
PAN_STROKE_GRADUAL_TRAN	Gradual/transitional
PAN_STROKE_GRADUAL_VERT	Gradual/vertical
PAN_STROKE_GRADUAL_HORZ	Gradual/horizontal
PAN_STROKE_RAPID_VERT	Rapid/vertical
PAN_STROKE_RAPID_HORZ	Rapid/horizontal
PAN_STROKE_INSTANT_VERT	Instant/vertical
bArmStyle

For Latin fonts, bArmStyle can have one of the following values:

Value	Meaning
PAN_ANY	Any
PAN_NO_FIT	No fit
PAN_STRAIGHT_ARMS_HORZ	Straight arms/horizontal
PAN_STRAIGHT_ARMS_WEDGE	Straight arms/wedge
PAN_STRAIGHT_ARMS_VERT	Straight arms/vertical
PAN_STRAIGHT_ARMS_SINGLE_SERIF	Straight arms/single-serif
PAN_STRAIGHT_ARMS_DOUBLE_SERIF	Straight arms/double-serif
PAN_BENT_ARMS_HORZ	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


PARAFORMAT  (preliminaryWindows NT)
PARAFORMAT  (preliminary−Windows NT)

typedef struct _paraformat {

    UINT cbSize;

    _WPAD _wPad1;

    DWORD dwMask;

    WORD  wNumbering;

    WORD  wReserved;

    LONG  dxStartIndent;

    LONG  dxRightIndent;

    LONG  dxOffset;

    WORD  wAlignment;

    SHORT cTabCount;

    LONG  rgxTabs[MAX_TAB_STOPS];

} PARAFORMAT;

The PARAFORMAT structure contains information about paragraph formatting attributes in a rich edit control. This structure is used with the EM_GETPARAFORMAT and EM_SETPARAFORMAT messages.

Members

cbSize

Size in bytes of this structure. Must be filled before passing to the rich edit control.

dwMask

Members containing valid information or attributes to set. This parameter can be zero or more of these values:

Value	Meaning
PFM_ALIGNMENT	The wAlignment member is valid.
PFM_NUMBERING	The wNumbering member is valid.
PFM_OFFSET	The dxOffset member is valid.
PFM_OFFSETINDENT	The dxStartIndent member is valid and specifies a relative value.
PFM_RIGHTINDENT	The dxRightIndent member is valid.
PFM_STARTINDENT	The dxStartIndent member is valid.
PFM_TABSTOPS	The cTabStobs and rgxTabStops members are valid.
If both PFM_STARTINDENT and PFM_OFFSETINDENT are specified, PFM_STARTINDENT takes precedence.

wNumbering

Value specifying numbering options. This member can be zero or PFN_BULLET.

dxStartIndent

Indentation of the first line in the paragraph. If the paragraph formatting is being set and PFM_OFFSETINDENT is specified, this member is treated as a relative value that is added to the starting indentation of each affected paragraph.

dxRightIndent

Size of the right indentation, relative to the right margin.

dxOffset

Indentation of the second line and subsequent lines, relative to the starting indentation. The first line is indented if this member is negative, or outdented is this member is positive.

wAlignment

Value specifying the paragraph alignment. This member can be one of the following values:

Value	Meaning
PFA_LEFT	Paragraphs are aligned with the left margin.
PFA_RIGHT	Paragraphs are aligned with the right margin.
PFA_CENTER	Paragraphs are centered.
cTabCount

Number of tab stops.

rgxTabs

Array of absolute tab stop positions.

See Also

EM_GETPARAFORMAT, EM_SETPARAFORMAT


PARTITION_INFORMATION

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 structure provides information about a disk partition.

Members

PartitionType

Specifies the type of partition. This member can be one of the following values:

Value	Meaning
PARTITION_ENTRY_UNUSED	Entry unused.
PARTITION_FAT_12	Specifies a partition with 12-bit FAT entries.
PARTITION_XENIX_1	Specifies a Xenix type 1 partition.
PARTITION_XENIX_2	Specifies a Xenix type 2 partition.
PARTITION_FAT_16	Specifies a partition with 16-bit FAT entries.
PARTITION_EXTENDED	Specifies an extended partition entry.
PARTITION_HUGE	Specifies an MS-DOS V4 huge partition.
PARTITION_IFS	Specifies an IFS partition.
PARTITION_UNIX	Specifies a Unix partition.
VALID_NTFT	Specifies an NTFT partition.
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.

Remarks

The DeviceIoControl function receives a PARTITION_INFORMATION structure in response to an IOCTL_DISK_GET_PARTITION_INFO or IOCTL_DISK_GET_DRIVE_LAYOUT device input and output control (IOCTL) operation. The DeviceIoControl function uses a PARTITION_INFORMATION structure as input to an IOCTL_DISK_SET_DRIVE_LAYOUT device IOCTL operation.

See Also

DeviceIoControl, IOCTL_DISK_GET_DRIVE_LAYOUT, IOCTL_DISK_GET_PARTITION_INFO, IOCTL_DISK_SET_DRIVE_LAYOUT


PERF_COUNTER_BLOCK

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.

Members

ByteLength

Specifies the length, in bytes, of this structure, including the counters that follow.

Remarks

This structure is part of the performance data provided by the RegQueryValueEx function when the HKEY_PERFORMANCE_DATA key is used.

See Also

PERF_OBJECT_TYPE, RegQueryValueEx


PERF_COUNTER_DEFINITION

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.

Members

ByteLength

Contains the length, in bytes, of this structure.

CounterNameTitleIndex

Contains the index of the counter name in the title database of the registry.

CounterNameTitle

Points to the name of the counter. This member contains NULL, initially, but it can contain a pointer to the actual string once the string is located.

CounterHelpTitleIndex

Contains the index to the counter's Help title in the title database of the registry.

CounterHelpTitle

Points to the title of Help. This member contains NULL, initially, but it can contain a pointer to the actual string once the string is located.

DefaultScale

Specifies the power of 10 by which to scale a chart line, assuming the vertical axis is 100. If this value is zero, the scale value is 1; if this value is 1, the scale value is 10; if this value is −1, the scale value is .10; and so on.

DetailLevel

Specifies the level of detail for the counter. Applications use this value to control display complexity. This member can be one of the following values:

Value	Meaning
PERF_DETAIL_NOVICE	The data can be understood by the uninformed user.
PERF_DETAIL_ADVANCED	The data is designed for the advanced user.
PERF_DETAIL_EXPERT	The data is designed for the expert user.
PERF_DETAIL_WIZARD	The data is designed for the system designer.
CounterType

Specifies the type of counter. This member is some combination of the following values.

These values indicate the counter's data size:

Value	Meaning
PERF_SIZE_DWORD	The counter data is a doubleword.
PERF_SIZE_LARGE	The counter data is a large integer.
PERF_SIZE_ZERO	The counter data is a zero-length field.
PERF_SIZE_VARIABLE_LEN	The size of the counter data is in the CounterSize member.
These values indicate the additional contents of this member:

Value	Meaning
PERF_TYPE_NUMBER	The counter data is a number value but not a counter.
PERF_TYPE_COUNTER	The counter data is an increasing numeric value.
PERF_TYPE_TEXT	The counter data is a text field.
PERF_TYPE_ZERO	The counter data is always zero.
If PERF_TYPE_NUMBER is specified, one of these values is also specified to indicate the format of the number:

Value	Meaning
PERF_NUMBER_HEX	The counter data should be displayed as a hexadecimal value.
PERF_NUMBER_DECIMAL	The counter data should be displayed as a decimal value.
PERF_NUMBER_DEC_1000	The counter data should be divided by 1000 and displayed as a decimal value.
If PERF_TYPE_COUNTER is specified, one of these values is also specified to indicate the type of counter:

Value	Meaning
PERF_COUNTER_VALUE	The counter value is valid without additional calculation; that is, it should be displayed as is.
PERF_COUNTER_RATE	The counter value should be divided by the elapsed time.
PERF_COUNTER_FRACTION	The counter value should be divided by the base value indicated by the next counter if it is of type PERF_COUNTER_BASE or by the value of the counter subtype.
PERF_COUNTER_BASE	The counter value is the base value to use in fractions.
PERF_COUNTER_ELAPSED	The counter value is a start time to be subtracted from the current time.
PERF_COUNTER_QUEUELEN	The performance application should use the Queuelen counter — that is, the Queue Length Space-Time Product formula. The next counter is the number currently in the queue. Multiply it by the current time (units specified by this counter's subtype). Add the product to the original value of the counter. To obtain the average queue length, divide the result of the addition by the delta time.
PERF_COUNTER_HISTOGRAM	The counter value begins or ends a histogram.
If PERF_TYPE_COUNTER is specified, one of these values is also specified to indicate the subtype of counter:

Value	Meaning
PERF_TIMER_TICK	The frequency of the high-resolution performance counter should be used as the base.
PERF_TIMER_100NS	The time base units of the 100-nanosecond timer should be used as the base.
PERF_OBJECT_TIMER	The object-timer frequency should be used as the base unit. This value is system-defined in this counter's PERF_OBJECT_TYPE definition.
If PERF_TYPE_TEXT is specified, one of these values is also specified to indicate the type of text:

Value	Meaning
PERF_TEXT_UNICODE	The counter data contains Unicode text.
PERF_TEXT_ASCII	The counter data contains ASCII text.
These values indicate how to use the counter data in a calculation:

Value	Meaning
PERF_DELTA_COUNTER	The difference between the previous counter value and the current counter value is computed before proceeding.
PERF_DELTA_BASE	The difference between the previous base value and the current base value is computed before proceeding.
PERF_INVERSE_COUNTER	After other calculations, the counter should be inverted before displaying or converting to a percentage.
PERF_MULTI_COUNTER	This value is a sum of counters from several sources, the number of which is indicated by the next counter.
These values indicate the display suffix of the counter data:

Value	Meaning
PERF_DISPLAY_NO_SUFFIX	There is no display suffix.
PERF_DISPLAY_PER_SEC	The display suffix is '/sec'.
PERF_DISPLAY_PERCENT	The display suffix is '%'.
PERF_DISPLAY_SECONDS	The display suffix is 'secs'.
PERF_DISPLAY_NOSHOW	The counter value should not be displayed.
CounterSize

Specifies the counter size, in bytes.

CounterOffset

Specifies the offset from the start of the PERF_COUNTER_BLOCK structure to the first byte of this counter.

Remarks

This structure is part of the performance data provided by the RegQueryValueEx function when the HKEY_PERFORMANCE_DATA key is used.

See Also

RegQueryValueEx


PERF_DATA_BLOCK

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.

Members

Signature

Contains the Unicode string PERF.

LittleEndian

Contains zero if the processor is big endian and one if it is little endian.

Version

Contains the version of the performance (PERF_) structures. This member is greater than or equal to one.

Revision

Contains the revision of the performance (PERF_) structures. This member is greater than or equal to zero.

TotalByteLength

Contains the total length, in bytes, of the performance data.

HeaderLength

Contains the length, in bytes, of this structure.

NumObjectTypes

Contains the number of object types being monitored.

DefaultObject

Contains the object title index of the default object whose performance data is to be displayed. This member can be −1 to indicate that no data is to be displayed.

SystemTime

Contains the time when the system is monitored. This member is in Coordinated Universal Time (UTC) format.

PerfTime

Contains the performance-counter value, in counts, for the system being monitored.

PerfFreq

Contains the performance-counter frequency, in counts per second, for the system being monitored.

PerfTime100nSec

Contains the performance-counter value, in 100 nanosecond units, for the system being monitored.

SystemNameLength

Contains the length, in bytes, of the system name.

SystemNameOffset

Contains the offset from the beginning of this structure to the name of the system being monitored.

See Also

PERF_OBJECT_TYPE, RegQueryValueEx


PERF_INSTANCE_DEFINITION

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.

Members

ByteLength

Specifies the length, in bytes, of this structure, including the subsequent name.

ParentObjectTitleIndex

Specifies the index of the name of the "parent" object in the title database. For example, if the object is a thread, the parent object type is a process, or if the object is a logical drive, the parent is a physical drive.

ParentObjectInstance

Specifies the index to an instance of the parent object type that is the parent of this instance. This member may be zero or greater.

UniqueID

Specifies the unique identifier used instead of the instance name. This member is PERF_NO_UNIQUE_ID if there is no such identifier.

NameOffset

Specifies the offset from the beginning of this structure to the Unicode name of this instance.

NameLength

Specifies the length, in bytes, of the instance name. This member is zero if the instance does not have a name.

See Also

PERF_DATA_BLOCK


PERF_OBJECT_TYPE

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 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.

Members

TotalByteLength

Contains the length, in bytes, of the object-specific data. This value includes this structure, the PERF_COUNTER_DEFINITION structures, and the PERF_INSTANCE_DEFINITION and PERF_COUNTER_BLOCK structures for each instance. This member specifies the offset from the beginning of this structure to the next PERF_OBJECT_TYPE structure if one exists.

DefinitionLength

Contains the length, in bytes, of the object-specific data. This value includes this structure and the PERF_COUNTER_DEFINITION structures for this object. This member is the offset from the beginning of the PERF_OBJECT_TYPE structure to the first PERF_INSTANCE_DEFINITION structure or to the PERF_COUNTER_DEFINITION structures if there is no instance data.

HeaderLength

Contains the length, in bytes, of this structure. This member is the offset to the first PERF_COUNTER_DEFINITION structure for this object.

ObjectNameTitleIndex

Contains the index to the object's name in the title database.

ObjectNameTitle

Points to the name of the object. This member initially contains NULL, but it can contain a pointer to the actual string once the string is located.

ObjectHelpTitleIndex

Contains the index to the object's Help title in the title database.

ObjectHelpTitle

Points to the title of Help. This member initially contains NULL, but it can contain a pointer to the actual string once the string is located.

DetailLevel

Specifies the level of detail. Applications use this value to control display complexity. This value is the minimum detail level of all the counters for a given object. This member can be one of the following values:

Detail level	Meaning
PERF_DETAIL_NOVICE	No technical ability is required to understand the counter data.
PERF_DETAIL_ADVANCED	The counter data is provided for advanced users.
PERF_DETAIL_EXPERT	The counter data is provided for expert users.
PERF_DETAIL_WIZARD	The counter data is provided for system designers.
NumCounters

Specifies the number of counters in each counter block. There is one counter block per instance.

DefaultCounter

Specifies the default counter whose information is to be displayed when this object is selected. This member is typically greater than or equal to zero. However, this member may be −1 to indicate that there is no default.

NumInstances

Specifies the number of object instances for which counters are being provided.

CodePage

Specifies the code page. This member is zero if the instance strings are in Unicode. Otherwise, this member is the code-page identifier of the instance names.

PerfTime

Specifies the current value, in counts, of the high-resolution performance counter.

PerfFreq

Specifies the current frequency, in counts per second, of the high-resolution performance counter.

Remarks

If there is only one instance of the object type, the counter definitions are followed by a single PERF_COUNTER_BLOCK structure. This structure is followed by data for each counter. (The PERF_COUNTER_BLOCK structure contains the total length of the structure and the counter data that follows it.)

If there is more than one instance of the object type, the list of counter definitions is followed by a PERF_INSTANCE_DEFINITION structure and a PERF_COUNTER_BLOCK structure for each instance. The PERF_INSTANCE_DEFINITION structure includes the name, the identifier, and the name of the parent of the instance.

Following the counter data, there is a PERF_INSTANCE_DEFINITION structure and a PERF_COUNTER_BLOCK structure for each instance specified in the PERF_DATA_BLOCK structure that begins the performance-data area.

See Also

PERF_COUNTER_BLOCK, PERF_COUNTER_DEFINITION, PERF_INSTANCE_DEFINITION


POINT

typedef struct tagPOINT { // pt

    LONG x;

    LONG y;

} POINT;

The POINT structure defines the x- and y- coordinates of a point.

Members

x

Specifies the x-coordinate of the point.

y

Specifies the y-coordinate of the point.

See Also

ChildWindowFromPoint, GetBrushOrgEx, PtInRect, SetBrushOrgEx, WindowFromPoint


POINTFX

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.

Members

x

Specifies the x-component of a point on the outline of a TrueType character.

y

Specifies the y-component of a point on the outline of a TrueType character.

Remarks

The POINTFX structure is a member of the TTPOLYCURVE and TTPOLYGONHEADER structures. Values in the POINTFX structure are specified in device units.

See Also

FIXED, TTPOLYCURVE, TTPOLYGONHEADER


POINTL

typedef struct _POINTL { // ptl

    LONG x;

    LONG y;

} POINTL;

The POINTL structure contains the coordinates of a point.

Members

x

Specifies the horizontal (x) coordinate of the point.

y

Specifies the vertical (y) coordinate of the point.


POINTS

typedef struct tagPOINTS { // pts

    SHORT x;

    SHORT y;

} POINTS;

The POINTS structure defines the coordinates of a point.

Members

x

Specifies the x-coordinate of the point.

y

Specifies the y-coordinate of the point.

See Also

ChildWindowFromPoint, PtInRect, WindowFromPoint, POINT


POLYTEXT

typedef struct _POLYTEXT { // ptxt

    int     x;

    int     y;

    UINT    n;

    LPCTSTR lpstr;

    UINT    uiFlags;

    RECT    rcl;

    int     *pdx;

} POLYTEXT;

The POLYTEXT structure describes how the PolyTextOut function should draw a string of text.

Members

x

Specifies the horizontal reference point for the string. The string is aligned to this point using the current text-alignment mode.

y

Specifies the vertical reference point for the string. The string is aligned to this point using the current text-alignment mode.

n

Specifies the number of characters in the string.

uiFlags

Specifies whether the string is to be opaque or clipped and whether the string is accompanied by an array of character-width values. This member can be one or more of the following values:

Value	Meaning
ETO_OPAQUE	The rectangles given for each string is to be opaqued with the current background color.
ETO_CLIPPED	Each string is to be clipped to its given rectangle.
lpstr

Points to a string of text to be drawn by the PolyTextOut function.

rcl

Specifies a rectangle structure that contains the dimensions of the opaquing or clipping rectangle. This member is ignored if neither of the ETO_OPAQUE nor the ETO_CLIPPED value is specified for the uiFlags member.

pdx

Specifies in an array the width value for each character in the string.

See Also

PolyTextOut


PORT_INFO_1

typedef struct _PORT_INFO_1 { // pi1

    LPTSTR pName;

} PORT_INFO_1;

The PORT_INFO_1 structure identifies a supported printer port.

Members

pName

Points to a null-terminated string that identifies a supported printer port (for example, "LPT1:").

See Also

EnumPorts


PORT_INFO_2  (preliminaryWindows 95)
PORT_INFO_2  [image]  (preliminary−Windows 95)

typedef struct _PORT_INFO_2 { // pi2

    LPSTR pPortName;

    LPSTR pMonitorName

    LPSTR pDescription;

    DWORD fPortType;

    DWORD Reserved;

} PORT_INFO_2;

The PORT_INFO_2 structure identifies a supported printer port.

Members

pPortName

Points to a null-terminated string that identifies a supported printer port (for example, "LPT1:").

pMonitorName

Points to a null-terminated string that identifies an installed monitor (for example, "PJL monitor").

pDescription

Points to a null-terminated string that describes the port in more detail (for example, if pPortName is "LPT1:", pDescription is "printer port").

fPortType

Identifies the type of port. Can be one of these values:

PORT_TYPE_WRITE

PORT_TYPE_READ

PORT_TYPE_REDIRECTED

PORT_TYPE_NET_ATTACHED

Reserved

Reserved; must be zero.

Remarks

Use the PORT_INFO_2 structure when calling EnumPorts if there are multiple monitors installed that support the same ports.

See Also

EnumPorts


PREVENT_MEDIA_REMOVAL

typedef struct _PREVENT_MEDIA_REMOVAL{

   BOOLEAN PreventMediaRemoval;

} PREVENT_MEDIA_REMOVAL ;

The PREVENT_MEDIA_REMOVAL structure provides removable media locking data.

Members

PreventMediaRemoval

Specifies whether the media is to be locked (if TRUE) or not (if FALSE).

Remarks

The DeviceIoControl function uses a PREVENT_MEDIA_REMOVAL structure as input to an IOCTL_DISK_MEDIA_REMOVAL device input and output operation.

See Also

DeviceIoControl, IOCTL_DISK_MEDIA_REMOVAL


PRINTDLG

typedef struct tagPD {  // pd

    DWORD     lStructSize;

    HWND      hwndOwner;

    HANDLE    hDevMode;

    HANDLE    hDevNames;

    HDC       hDC;

    DWORD     Flags;

    WORD      nFromPage;

    WORD      nToPage;

    WORD      nMinPage;

    WORD      nMaxPage;

    WORD      nCopies;

    HINSTANCE hInstance;

    DWORD     lCustData;

    LPPRINTHOOKPROC lpfnPrintHook;

    LPSETUPHOOKPROC lpfnSetupHook;

    LPCTSTR    lpPrintTemplateName;

    LPCTSTR    lpSetupTemplateName;

    HANDLE    hPrintTemplate;

    HANDLE    hSetupTemplate;

} PRINTDLG;

The PRINTDLG structure contains information the 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 selections in this structure.

Members

lStructSize

Specifies the structure size, in bytes.

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

hDevMode

Identifies a movable global memory object that contains a DEVMODE structure. Before a call to the PrintDlg function, the structure members may contain data used to initialize the dialog controls. When PrintDlg returns, the structure members specify the state of the dialog box controls.

If 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, hDevMode may be NULL. In this case, PrintDlg allocates memory for the structure, initializes its members, and returns a handle that identifies it.

If the device driver for the specified printer does not support extended device modes, hDevMode is NULL when PrintDlg returns.

If the device name (specified by the dmDeviceName member of the DEVMODE structure) does not appear in the [devices] section of WIN.INI, PrintDlg returns an error.

Because this structure is a movable global memory object, the value of hDevMode may change during the execution of PrintDlg.

For a discussion of how the system resolves a possible data collision between values specified by the hDevMode and hDevNames members, see the Remarks section later in this topic.

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 DEVNAMES 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, hDevNames may be NULL. In this case, PrintDlg allocates memory for the structure, initializes its members (by using the printer name specified in the DEVMODE structure), and returns a handle that identifies it. PrintDlg uses the first port name that appears in the [devices] section of WIN.INI when it initializes the members in the DEVNAMES structure. For example, the function uses "LPT1:" as the port name if the following string appears in the [devices] section:

PCL / HP LaserJet=HPPCL,LPT1:,LPT2:

If both hDevMode and hDevNames are NULL, PrintDlg initializes hDevNames using the current default printer.

Because this structure is a movable global memory object, the value of hDevNames may change during the execution of PrintDlg.

For a discussion of how the system resolves a possible data collision between values specified by hDevNames and hDevMode, see the Remarks section later in this topic.

hDC

Identifies a device context or an information context, depending on whether the Flags member specifies the PD_RETURNDC or PC_RETURNIC flag. If neither flag is specified, the value of this member is undefined. If both flags are specified, PD_RETURNDC has priority.

Flags

Specifies the dialog box initialization flags. This member may be a combination of the following flags:

Flag	Meaning
PD_ALLPAGES
	Indicates that the All radio button was selected when the user closed the dialog box. (This flag is used as a placeholder to indicate that the PD_PAGENUMS and PD_SELECTION flags are not specified. This flag can be set on input and on output.)
PD_COLLATE
	Places a checkmark in the Collate check box when set on input. When the PrintDlg function returns, this value indicates that the user selected the Collate option and the printer driver does not support collation. In this case, the application must provide collation. If PrintDlg sets the PD_COLLATE value on return, it also sets dmCollate in the DEVMODE structure to COLLATE_TRUE.
PD_DISABLEPRINTTOFILE
	Disables the Print to File check box.
PD_ENABLEPRINTHOOK
	Enables the hook function specified in lpfnPrintHook.
PD_ENABLEPRINTTEMPLATE
	Causes the system to create the dialog box by using the dialog box template identified by hInstance and lpPrintTemplateName.
PD_ENABLEPRINTTEMPLATEHANDLE
	Indicates that hInstance identifies a data block that contains a preloaded dialog box template. The system ignores lpPrintTemplateName if this flag is specified.
PD_ENABLESETUPHOOK
	Enables the hook function specified in lpfnSetupHook.
PD_ENABLESETUPTEMPLATE
	Causes the operating system to create the dialog box by using the dialog template box identified by hInstance and lpSetupTemplateName.
PD_ENABLESETUPTEMPLATEHANDLE
	Indicates that hInstance identifies a data block that contains a preloaded dialog box template. The system ignores lpSetupTemplateName 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 PrintDlg returns, this flag is specified 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 PrintDlg returns, the pOutput member of the DEVNAMES structure points to the "FILE:" string.
PD_RETURNDC
	Causes PrintDlg to return a device context matching the selections the user made in the dialog box. The device context is returned in hDC.
PD_RETURNDEFAULT
	Causes PrintDlg to return DEVMODE and DEVNAMES structures that are initialized for the system default printer without displaying a dialog box. It is assumed that both hDevNames and hDevMode are NULL; otherwise, the function returns an error. If the system default printer is supported by an old printer driver (earlier than Windows version 3.0), only hDevNames is returned; hDevMode is NULL.
PD_RETURNIC
	Similar to the PD_RETURNDC flag except that this flag returns an information context rather than a device context. If neither PD_RETURNDC nor PD_RETURNIC is specified, hDC is undefined on output.
PD_SELECTION
	Causes the Selection radio button to be in the selected state when the dialog box is created. When PrintDlg returns, this flag is specified if the Selection radio button is 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 flag is specified.
PD_USEDEVMODECOPIES
	Same as PD_USEDEVMODECOPIESANDCOLLATE
PD_USEDEVMODECOPIESANDCOLLATE
	Disables the Copies edit control if the printer driver does not support multiple copies and disables the Collate checkbox if the printer driver does not support collation. Otherwise, directs PrintDlg to store the user selections for the Copies and Collate options in the dmCopies and dmCollate members of the DEVMODE structure.
	If the driver supports multiple copies, PrintDlg stores the requested number of copies in the dmCopies member of the DEVMODE structure and stores the value 1 in the nCopies member of the PRINTDLG structure. If this flag is not specified, dmCopies receives 1 and nCopies receives the requested number of copies.
	If the driver supports collation, PrintDlg sets the dmCollate member of the DEVMODE structure to DMCOLLATE_TRUE or DMCOLLATE_FALSE, depending on the user selection. If this flag is not specified, dmCollate is ignored and the Flags member of PRINTDLG is set to PD_COLLATE only if the user selects the Collate option.
nFromPage

Specifies the initial value for the starting page edit control. When the PrintDlg function returns, this member specifies the page at which 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

Contains the initial number of copies for the Copies edit control if hDevMode is NULL; otherwise, the dmCopies member of the DEVMODE structure contains the initial value. When PrintDlg returns, this member contains the actual number of copies to print. If the printer driver does not support multiple copies, this value may be greater than one and the application must print all requested copies. If the PD_USEDEVMODECOPIESANDCOLLATE value is set in the Flags member, nCopies is always set to 1 on return and the dmCopies member in the DEVMODE receives the actual number of copies to print.

hInstance

Identifies a data block that contains the preloaded dialog box template specified by lpPrintTemplateName or lpSetupTemplateName. This member is used only if Flags 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 lpfnHook. 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 Flags member specifies the PD_ENABLEPRINTHOOK flag.

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 Flags member specifies the PD_ENABLESETUPHOOK flag.

lpPrintTemplateName

Specifies the name of the Print dialog box template identified by hInstance.

lpSetupTemplateName

Specifies the name of the Print Setup dialog box identified by hInstance.

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.

Remarks

There might be data collision between the values specified by hDevNames and hDevMode because the wDeviceOffset member of the DEVNAMES structure is supposed to be identical to the dmDeviceName member of the DEVMODE structure. If it is not, the system resolves the data collision by using the value of wDeviceOffset.

See Also

CreateDC, CreateIC, PrintDlg, DEVMODE, DEVNAMES, WM_INITDIALOG


PRINTER_DEFAULTS

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 access rights for a printer.

Members

pDatatype

Points to a null-terminated string that specifies the default data type for a printer.

pDevMode

Points to a DEVMODE structure that identifies the default environment and initialization data for a printer.

DesiredAccess

Specifies desired access rights for a printer. The OpenPrinter function uses this member to set access rights to the printer. These rights can affect the operation of the SetPrinter and DeletePrinter functions.

This member can be set to PRINTER_ACCESS_ADMINISTER, PRINTER_ACCESS_USE, or any generic security value (for example, WRITE_DACL). If an application wishes to open a printer to perform administrative tasks, such as the SetPrinter function, it must open the printer with PRINTER_ACCESS_ADMINISTER access.

See Also

DeletePrinter, DEVMODE, OpenPrinter, SetPrinter


PRINTER_INFO_1

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.

Members

Flags

Specifies information about the returned data. Following are the values for this member

Value	Meaning
PRINTER_ENUM_EXPAND	A print provider can set this flag as a hint to a calling application to enumerate this object further if default expansion is enabled. For example, when domains are enumerated, a print provider might indicate the user's domain by setting this flag.
PRINTER_ENUM_CONTAINER	If this flag is set, the printer object may contain enumerable objects. For example, the object may be a print server that contains printers.
PRINTER_ENUM_ICON1	Indicates that, where appropriate, an application should display an icon identifying the object as a top-level network name, such as Microsoft Windows Network.
PRINTER_ENUM_ICON2	Indicates that, where appropriate, an application should display an icon that identifies the object as a network domain.
PRINTER_ENUM_ICON3	Indicates that, where appropriate, an application should display an icon that identifies the object as a print server.
PRINTER_ENUM_ICON4	Reserved for future use.
PRINTER_ENUM_ICON5	Reserved for future use.
PRINTER_ENUM_ICON6	Reserved for future use.
PRINTER_ENUM_ICON7	Reserved for future use.
PRINTER_ENUM_ICON8	Indicates that, where appropriate, an application should display an icon that identifies the object as a printer.
pDescription

Windows NT: Points to a null-terminated string that describes the contents of the structure.

Windows 95: Points to a null-terminated string that describes the printer. The string contains the pPrinterName, pDriverName, and pComment members of the PRINTER_INFO_2 structure concatenated and separated by commas.

pName

Windows NT: Points to a null-terminated string that names the contents of the structure.

Windows 95: Points to a null-terminated string that specifies the name of the printer.

pComment

Windows NT: Points to a null-terminated string that contains additional data describing the structure.

Windows 95: Points to a null-terminated string that provides a brief description of the printer.

See Also

GetPrinter, EnumPrinters, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4


PRINTER_INFO_2

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.

Members

pServerName

Points to a null-terminated string identifying the server that controls the printer. If this string is NULL, the printer is controlled locally.

pPrinterName

Points to a null-terminated string that specifies the name of the printer.

pShareName

Points to a null-terminated string that identifies the sharepoint for the printer. (This string is used only if the PRINTER_ATTRIBUTE_SHARED constant was set for the Attributes member.)

pPortName

Points to a null-terminated string that identifies the port(s) used to transmit data to the printer. If a printer is connected to more than one port, the names of each port must be separated by commas (for example, "LPT1:,LPT2:,LPT3:").

pDriverName

Points to a null-terminated string that specifies the name of the printer driver.

pComment

Points to a null-terminated string that provides a brief description of the printer.

pLocation

Points to a null-terminated string that specifies the physical location of the printer (for example, "Bldg. 38, Room 1164").

pDevMode

Points to a DEVMODE structure that defines default printer data such as the paper orientation and the resolution.

pSepFile

Points to a null-terminated string that specifies the name of the file used to create the separator page. This page is used to separate print jobs sent to the printer.

pPrintProcessor

Points to a null-terminated string that specifies the name of the print processor used by the printer.

pDatatype

Points to a null-terminated string that specifies the data type used to record the print job.

pParameters

Points to a null-terminated string that specifies the default print-processor parameters.

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure for the printer. This member may be NULL.

Attributes

Specifies the printer attributes. This member can be one of the following values:

PRINTER_ATTRIBUTE_QUEUED
PRINTER_ATTRIBUTE_DIRECT
PRINTER_ATTRIBUTE_DEFAULT
PRINTER_ATTRIBUTE_SHARED
PRINTER_ATTRIBUTE_WORK_OFFLINE (Windows 95 only)

Priority

Specifies a priority value that the spooler uses to route print jobs.

DefaultPriority

Specifies the default priority value assigned to each print job.

StartTime

Specifies the earliest time at which the printer will print a job. (This value is 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:

Windows NT:

PRINTER_STATUS_PAUSED
PRINTER_STATUS_PENDING_DELETION

Windows 95:

PRINTER_STATUS_BUSY
PRINTER_STATUS_DOOR_OPEN
PRINTER_STATUS_ERROR
PRINTER_STATUS_INITIALIZING
PRINTER_STATUS_IO_ACTIVE
PRINTER_STATUS_MANUAL_FEED
PRINTER_STATUS_NO_TONER
PRINTER_STATUS_NOT_AVAILABLE
PRINTER_STATUS_OFFLINE
PRINTER_STATUS_OUT_OF_MEMORY
PRINTER_STATUS_OUTPUT_BIN_FULL
PRINTER_STATUS_PAGE_PUNT
PRINTER_STATUS_PAPER_JAM
PRINTER_STATUS_PAPER_OUT
PRINTER_STATUS_PAPER_PROBLEM
PRINTER_STATUS_PAUSED
PRINTER_STATUS_PENDING_DELETION
PRINTER_STATUS_PRINTING
PRINTER_STATUS_PROCESSING
PRINTER_STATUS_TONER_LOW
PRINTER_STATUS_UNAVAILABLE
PRINTER_STATUS_USER_INTERVENTION
PRINTER_STATUS_WAITING
PRINTER_STATUS_WARMING_UP

cJobs

Specifies the number of print jobs that have been queued for the printer.

AveragePPM

Specifies the average number of pages per minute that have been printed on the printer.

Remarks

Windows 95: The PRINTER_STATUS_PAGE_PUNT value specifies that the page is being "punted" (that is, not printed) because it is too complex for the printer to print.

See Also

DEVMODE, EnumPrinters, PRINTER_INFO_1, PRINTER_INFO_3, PRINTER_INFO_4, SECURITY_DESCRIPTOR


PRINTER_INFO_3

typedef struct _PRINTER_INFO_3 { // pri3

    PSECURITY_DESCRIPTOR pSecurityDescriptor;

} PRINTER_INFO_3;

The PRINTER_INFO_3 structure specifies printer security information.

Members

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure that specifies a printer's security information.

Remarks

The PRINTER_INFO_3 structure lets an application get and set a printer's security descriptor. The caller may do so even if it lacks specific printer permissions, as long as it has the standard rights described in SetPrinter and GetPrinter. Thus, an application may temporarily deny all access to a printer, while allowing the owner of the printer to have access to the printer's discretionary ACL.

See Also

SetPrinter, GetPrinter, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_4, SECURITY_DESCRIPTOR


PRINTER_INFO_4

typedef struct _PRINTER_INFO_4 { // pri4

    LPTSTR  pPrinterName;

    LPTSTR  pServerName;

    DWORD  Attributes;

} PRINTER_INFO_4;

The PRINTER_INFO_4 structure specifies general printer information.

The structure can be used to retrieve minimal printer information on a call to EnumPrinters. Such a call is a fast and easy way to retrieve the names and attributes of all locally installed printers on a system and all remote printer connections that a user has established.

Members

pPrinterName

Points to a null-terminated string that specifies the name of the printer (local or remote).

pServerName

Points to a null-terminated string that is the name of the server.

Attributes

Specifies information about the returned data.

Value	Meaning
PRINTER_ATTRIBUTE_LOCAL	The printer is a local printer.
PRINTER_ATTRIBUTE_NETWORK	The printer is a remote printer.
Remarks

The PRINTER_INFO_4 structure provides an easy and extremely fast way to retrieve the names of the printers installed on a local machine, as well as the remote connections that a user has established. When EnumPrinters is called with a PRINTER_INFO_4 data structure, that function queries the registry for the specified information, then returns immediately. This differs from the behavior of EnumPrinters when called with other levels of PRINTER_INFO_xxx data structures. In particular, when EnumPrinters is called with a level 2 (PRINTER_INFO_2) data structure, it performs an OpenPrinter call on each remote connection. If a remote connection is down, if the remote server no longer exists, or if the remote printer no longer exists, the function must wait for RPC to time out and consequently fail the OpenPrinter call. This can take a while. Passing a PRINTER_INFO_4 structure lets an application retrieve a bare minimium of required information; if more detailed information is desired, a subsequent EnumPrinter level 2 call can be made.

See Also

GetPrinter, EnumPrinters, OpenPrinter, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_3


PRINTER_INFO_5  (preliminaryWindows 95)
PRINTER_INFO_5  [image]  (preliminary−Windows 95)

typedef struct _PRINTER_INFO_5 { // pri5

    LPTSTR    pPrinterName;

    LPTSTR    pPortName;

    DWORD     Attributes;

    DWORD     DeviceNotSelectedTimeout;

    DWORD     TransmissionRetryTimeout;

} PRINTER_INFO_5;

The PRINTER_INFO_5 structure specifies detailed printer information.

Members

pPrinterName

Points to a null-terminated string that specifies the name of the printer.

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:").

Attributes

Specifies the printer attributes. This member can be one of the following values:

PRINTER_ATTRIBUTE_QUEUED
PRINTER_ATTRIBUTE_DIRECT
PRINTER_ATTRIBUTE_DEFAULT
PRINTER_ATTRIBUTE_SHARED
PRINTER_ATTRIBUTE_WORK_OFFLINE

DeviceNotSelectedTimeout

Specifies the maximum time, in milliseconds, allowed to elapse between attempts to select a device.

TransmissionRetryTimeout

Specifies the maximum time, in milliseconds, allowed to elapse between transmission retries.

See Also

EnumPrinters, GetPrinter, SetPrinter, PRINTER_INFO_1, PRINTER_INFO_2, PRINTER_INFO_3, PRINTER_INFO_4


PRINTER_NOTIFY_INFO

typedef struct _PRINTER_NOTIFY_INFO {

    DWORD  Version;

    DWORD  Flags;

    DWORD  Count;

    PRINTER_NOTIFY_INFO_DATA  aData[1];

} PRINTER_NOTIFY_INFO;

The PRINTER_NOTIFY_INFO structure contains printer information returned by the FindNextPrinterChangeNotification function. The function returns this information after a wait operation on a printer change notification object has been satisfied.

Members

Version

Specifies the version of this structure. Set this member to 2.

Flags

Contains a bit flag to indicate the state of the notification structure. If the PRINTER_NOTIFY_INFO_DISCARDED bit is set, it indicates that some notifications had to be discarded.

Count

Specifies the number of PRINTER_NOTIFY_INFO_DATA elements in the aData array.

aData

An array of PRINTER_NOTIFY_INFO_DATA structures. Each element of the array identifies a single job or printer information field, and provides the current data for that field.

Remarks

If the Flags member has the PRINTER_NOTIFY_INFO_DISCARDED bit set, this indicates that an overflow or error occured, and notifications may have been lost. In this case, you must call FindNextPrinterChangeNotification and specify the PRINTER_NOTIFY_OPTIONS_REFRESH flag to retrieve all current information. Until you request this refresh operation, the system will not send additional notifications for this change notification object.

See Also

FindNextPrinterChangeNotification, PRINTER_NOTIFY_INFO_DATA


PRINTER_NOTIFY_INFO_DATA

typedef struct _PRINTER_NOTIFY_INFO_DATA {

    WORD   Type;

    WORD   Field;

    DWORD  Reserved;

    DWORD  Id;

    union {

        DWORD  adwData[2];

        struct {

            DWORD  cbBuf;

            LPVOID pBuf;

        } Data;

    } NotifyData;

} PRINTER_NOTIFY_INFO_DATA;

The PRINTER_NOTIFY_INFO_DATA structure identifies a job or printer information field and provides the current data for that field.

The FindNextPrinterChangeNotification function returns a PRINTER_NOTIFY_INFO structure, which contains an array of PRINTER_NOTIFY_INFO_DATA structures.

Members

Type

Indicates the type of information provided. This member can be one of the following values:

Value	Meaning
PRINTER_NOTIFY_TYPE	Indicates that the Field member specifies a PRINTER_NOTIFY_FIELD_* constant.
JOB_NOTIFY_TYPE	Indicates that the Field member specifies a JOB_NOTIFY_FIELD_* constant.
Field

Indicates the field that changed. For a list of possible values, see the following Remarks section.

Reserved

Reserved.

Id

Indicates the job identifier if the Type member specifies JOB_NOTIFY_TYPE. If the Type member specfies PRINTER_NOTIFY_TYPE, this member is undefined.

NotifyData

A union of data information based on the Type and Field members. For a description of the type of data associated with each field, see the following Remarks section.

The NotifyData union can be one of the following members:

Member	Meaning
adwData	An array of two DWORD values. For information fields that use only a single DWORD, the data is in adwData[0]
Data	The following members are contained in the Data structure:
Member	Meaning
cbBuf	Indicates the size, in bytes, of the buffer pointed to by pBuf.
pBuf	Points to a buffer that contains the field's current data.
Remarks

For most job and printer information fields, FindNextPrinterChangeNotification collapses multiple notifications for the same field into a single notification. When this happens, the field's data reflects only the last change. The following tables indicate which fields are not collapsible. If the Type member specifies PRINTER_NOTIFY_TYPE, the Field member can be one of the following values:

Field	Type of data
PRINTER_NOTIFY_FIELD_PRINTER_NAME
	pBuf points to a null-terminated string containing the name of the printer.
PRINTER_NOTIFY_FIELD_SHARE_NAME
	pBuf points to a null-terminated string that identifies the sharepoint for the printer.
PRINTER_NOTIFY_FIELD_DRIVER_NAME
	pBuf points to a null-terminated string containing the name of the printer's driver.
PRINTER_NOTIFY_FIELD_COMMENT
	pBuf points to a null-terminated string containing the new comment string, which is typically a brief description of the printer.
PRINTER_NOTIFY_FIELD_LOCATION
	pBuf points to a null-terminated string containing the new physical location of the printer (for example, "Bldg. 38, Room 1164").
PRINTER_NOTIFY_FIELD_DEVMODE
	pBuf points to a DEVMODE structure that defines default printer data such as the paper orientation and the resolution.
PRINTER_NOTIFY_FIELD_SEPFILE
	pBuf points to a null-terminated string that specifies the name of the file used to create the separator page. This page is used to separate print jobs sent to the printer.
PRINTER_NOTIFY_FIELD_PRINT_PROCESSOR
	pBuf points to a null-terminated string that specifies the name of the print processor used by the printer.
PRINTER_NOTIFY_FIELD_PARAMETERS
	pBuf points to a null-terminated string that specifies the default print-processor parameters.
PRINTER_NOTIFY_FIELD_DATATYPE
	pBuf points to a null-terminated string that specifies the data type used to record the print job.
PRINTER_NOTIFY_FIELD_SECURITY_DESCRIPTOR
	pBuf points to a SECURITY_DESCRIPTOR structure for the printer. The pointer may be NULL if there is no security descriptor.
PRINTER_NOTIFY_FIELD_ATTRIBUTES
	adwData[0] specifies the printer attributes, which can be one of the following values:  PRINTER_ATTRIBUTE_QUEUED PRINTER_ATTRIBUTE_DIRECT PRINTER_ATTRIBUTE_DEFAULT PRINTER_ATTRIBUTE_SHARED Windows 95 only: PRINTER_ATTRIBUTE_WORK_OFFLINE  Not collapsible.
PRINTER_NOTIFY_FIELD_PRIORITY
	adwData[0] specifies a priority value that the spooler uses to route print jobs.
PRINTER_NOTIFY_FIELD_DEFAULT_PRIORITY
	adwData[0] specifies the default priority value assigned to each print job.
PRINTER_NOTIFY_FIELD_START_TIME
	adwData[0] specifies the earliest time at which the printer will print a job. (This value is specified in minutes elapsed since 12:00 A.M.)
PRINTER_NOTIFY_FIELD_UNTIL_TIME
	adwData[0] specifies the latest time at which the printer will print a job. (This value is specified in minutes elapsed since 12:00 A.M.)
PRINTER_NOTIFY_FIELD_STATUS
	adwData[0] specifies the printer status. For a list of possible values, see the PRINTER_INFO_2 structure. Not collapsible.
PRINTER_NOTIFY_FIELD_CJOBS
	adwData[0] specifies the number of print jobs that have been queued for the printer.
PRINTER_NOTIFY_FIELD_AVERAGE_PPM
	adwData[0] specifies the average number of pages per minute that have been printed on the printer.

If the Type member specifies JOB_NOTIFY_TYPE, the Field member can be one of the following values:

Field	Type of data
JOB_NOTIFY_FIELD_PRINTER_NAME
	pBuf points to a null-terminated string containing the name of the printer for which the job is spooled.
JOB_NOTIFY_FIELD_MACHINE_NAME
	pBuf points to a null-terminated string that specifies the name of the machine that created the print job.
JOB_NOTIFY_FIELD_PORT_NAME
	pBuf points to a null-terminated string that identifies the port(s) used to transmit data to the printer. If a printer is connected to more than one port, the names of the ports are separated by commas (for example, "LPT1:,LPT2:,LPT3:").
JOB_NOTIFY_FIELD_USER_NAME
	pBuf points to a null-terminated string that specifies the name of the user who sent the print job.
JOB_NOTIFY_FIELD_NOTIFY_NAME
	pBuf points to a null-terminated string that specifies the name of the user who should be notified when the job has been printed or when an error occurs while printing the job.
JOB_NOTIFY_FIELD_DATATYPE
	pBuf points to a null-terminated string that specifies the type of data used to record the print job.
JOB_NOTIFY_FIELD_PRINT_PROCESSOR
	pBuf points to a null-terminated string that specifies the name of the print processor to be used to print the job.
JOB_NOTIFY_FIELD_PARAMETERS
	pBuf points to a null-terminated string that specifies print-processor parameters.
JOB_NOTIFY_FIELD_DRIVER_NAME
	pBuf points to a null-terminated string that specifies the name of the printer driver that should be used to process the print job.
JOB_NOTIFY_FIELD_DEVMODE
	pBuf points to a DEVMODE structure that contains device-initialization and environment data for the printer driver.
JOB_NOTIFY_FIELD_STATUS
	adwData[0] specifies the job status. For a list of possible values, see the JOB_INFO_2 structure. Not collapsible.
JOB_NOTIFY_FIELD_STATUS_STRING
	pBuf points to a null-terminated string that specifies the status of the print job.
JOB_NOTIFY_FIELD_DOCUMENT
	pBuf points to a null-terminated string that specifies the name of the print job (for example, "MS-WORD: Review.doc").
JOB_NOTIFY_FIELD_PRIORITY
	adwData[0] specifies the job priority.
JOB_NOTIFY_FIELD_POSITION
	adwData[0] specifies the job's position in the print queue.  Not collapsible.
JOB_NOTIFY_FIELD_SUBMITTED
	pBuf points to a SYSTEMTIME structure that specifies the time when the job was submitted.
JOB_NOTIFY_FIELD_START_TIME
	adwData[0] specifies the earliest time that the job can be printed.
JOB_NOTIFY_FIELD_UNTIL_TIME
	adwData[0] specifies the the latest time that the job can be printed.
JOB_NOTIFY_FIELD_TIME
	adwData[0] specifies the total time, in seconds, that has elapsed since the job began printing.
JOB_NOTIFY_FIELD_TOTAL_PAGES
	adwData[0] specifies the size, in pages, of the job.
JOB_NOTIFY_FIELD_PAGES_PRINTED
	adwData[0] specifies the number of pages that have printed.
JOB_NOTIFY_FIELD_TOTAL_BYTES
	adwData[0] specifies the size, in bytes, of the job.
JOB_NOTIFY_FIELD_BYTES_PRINTED
	adwData[0] specifies the number of bytes that have been printed on this job. For this field, the change notification object is signaled when bytes are sent to the printer.
See Also

DEVMODE, FindNextPrinterChangeNotification, JOB_INFO_2, PRINTER_INFO_2, PRINTER_NOTIFY_INFO, SECURITY_DESCRIPTOR, SYSTEMTIME


PRINTER_NOTIFY_OPTIONS

typedef struct _PRINTER_NOTIFY_OPTIONS {

    DWORD  Version;

    DWORD  Flags;

    DWORD  Count;

    PPRINTER_NOTIFY_OPTIONS_TYPE  pTypes;

} PRINTER_NOTIFY_OPTIONS;

The PRINTER_NOTIFY_OPTIONS structure specifies options for a change notification object that monitors a printer or print server.

Members

Version

Specifies the version of this structure. Set this member to 2.

Flags

Contains a bit flag. If you set the PRINTER_NOTIFY_OPTIONS_REFRESH flag in a call to the FindNextPrinterChangeNotification function, the function provides current data for all monitored printer information fields. The FindFirstPrinterChangeNotification function ignores the Flags member.

Count

Specifies the number of elements in the pTypes array.

pTypes

Points to an array of PRINTER_NOTIFY_OPTIONS_TYPE structures. Use one element of this array to specify the printer information fields to monitor, and one element to specify the job information fields to monitor. You can monitor either printer information, job information, or both.

Remarks

Use this structure with the FindFirstPrinterChangeNotification function to specify the set of printer or job information fields to monitor for change.

Use this structure with the FindNextPrinterChangeNotification function to request the current data for all monitored printer and job information fields. In this case, the Flags member specifies the PRINTER_NOTIFY_OPTIONS_REFRESH flag, and the function ignores the other structure members.

See Also

FindFirstPrinterChangeNotification, FindNextPrinterChangeNotification, PRINTER_NOTIFY_OPTIONS_TYPE


PRINTER_NOTIFY_OPTIONS_TYPE

typedef struct _PRINTER_NOTIFY_OPTIONS_TYPE {

    WORD   Type;

    WORD   Reserved0;

    DWORD  Reserved1;

    DWORD  Reserved2;

    DWORD  Count;

    PWORD  pFields;

} PRINTER_NOTIFY_OPTIONS_TYPE;

The PRINTER_NOTIFY_OPTIONS_TYPE structure specifies the set of printer or job information fields to be monitored by a printer change notification object.

A call to the FindFirstPrinterChangeNotification function specifies a PRINTER_NOTIFY_OPTIONS structure, which contains an array of PRINTER_NOTIFY_OPTIONS_TYPE structures.

Members

Type

Specifies the type to watch. This member can be one of the following values:

Value	Meaning
PRINTER_NOTIFY_TYPE	Indicates that the fields specified in the pFields array are PRINTER_NOTIFY_FIELD_* constants.
JOB_NOTIFY_TYPE	Indicates that the fields specified in the pFields array are JOB_NOTIFY_FIELD_* constants.
Reserved0

Reserved.

Reserved1

Reserved.

Reserved2

Reserved.

Count

Specifies the number of elements in the pFields array.

pFields

Points to an array of 16-bit values. Each element of the array specifies a job or printer information field of interest. For a list of supported printer and job information fields, see the PRINTER_NOTIFY_INFO_DATA structure.

See Also

FindFirstPrinterChangeNotification, PRINTER_NOTIFY_INFO_DATA, PRINTER_NOTIFY_OPTIONS


PRINTPROCESSOR_INFO_1

typedef struct _PRINTPROCESSOR_INFO_1 { // ppi1

    LPTSTR pName;

} PRINTPROCESSOR_INFO_1;

The PRINTPROCESSOR_INFO_1 structure specifies the name of an installed print processor.

Members

pName

Points to a null-terminated string that specifies the name of an installed print processor.

See Also

EnumPrintProcessors


PRIVILEGE_SET

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.

Members

PrivilegeCount

Specifies the number of privileges in the privilege set.

Control

Specifies a control flag related to the privileges. The PRIVILEGE_SET_ALL_NECESSARY control flag is currently defined. It indicates that all of the specified privileges must be held by the process requesting access. If this flag is not set, the presence of any privileges in the user's access token grants the access.

Privilege

Specifies an array of LUID_AND_ATTRIBUTES structures describing the set's privileges. The following attributes are defined for privileges:

Attribute	Description
SE_PRIVILEGE_ENABLED_BY_DEFAULT
	The privilege is enabled by default.
SE_PRIVILEGE_ENABLED
	The privilege is enabled.
SE_PRIVILEGE_USED_FOR_ACCESS
	The privilege was used to gain access to an object or service. This flag is used to identify the relevant privileges in a set passed by a client application that may contain unnecessary privileges.
Remarks

A privilege is used to control access to an object or service more strictly than is typical with discretionary access control. A system manager uses privileges to control which users are able to manipulate system resources. An application uses privileges when it changes a system-wide resource, such as when it changes the system time or shuts down the system.

See Also

PrivilegeCheck, LUID, LUID_AND_ATTRIBUTES


PROCESS_HEAP_ENTRY

typedef struct _PROCESS_HEAP_ENTRY {

    PVOID lpData;

    DWORD cbData;

    BYTE cbOverhead;

    BYTE iRegionIndex;

    WORD wFlags;

    DWORD dwCommittedSize;

    DWORD dwUnCommittedSize;

    LPVOID lpFirstBlock;

    LPVOID lpLastBlock;

    HANDLE hMem;

} PROCESS_HEAPENTRY;

The PROCESS_HEAP_ENTRY structure contains information about a memory block in a heap. A memory block in a heap is also known as a heap entry or a heap element. The HeapWalk function uses a PROCESS_HEAP_ENTRY structure to enumerate the elements of a heap.

Members

lpData

Points to the data portion of the heap element.

If either the PROCESS_HEAP_REGION or the PROCESS_HEAP_UNCOMMITTED RANGE bit flag is set in the wFlags member, the meaning of lpData changes. For details of the change, see the following discussion of those flags.

cbData

Specifies the size, in bytes, of the data portion of the heap element.

If either the PROCESS_HEAP_REGION or the PROCESS_HEAP_UNCOMMITTED RANGE bit flag is set in the wFlags member, the meaning of cbData changes. For details of the change, see the following discussion of those flags.

cbOverhead

Specifies the size, in bytes, of additional data used by the system to maintain information about the heap element. In this context, "additional" means that the data is stored outside the data portion pointed to by lpData.

If either the PROCESS_HEAP_REGION or the PROCESS_HEAP_UNCOMMITTED RANGE bit flag is set in the wFlags member, the meaning of cbOverhead changes. For details of the change, see the following discussion of those flags.

iRegionIndex

A zero-based index that specifies the region of virtual memory within the heap that contains the heap element. A heap consists of one or more regions of virtual memory.

wFlags

A set of bit flags that specify properties of the heap element. Some of these flags affect the meaning of other members of this PROCESS_HEAP_ENTRY data structure. The following bit-flag constants are defined:

Value	Meaning
PROCESS_HEAP_REGION	If this flag is set, the heap element is located at the beginning of a region of contiguous virtual memory in use by the heap.  If this flag is set, the meanings of the following members of this structure change: The lpData member of the structure points to the first virtual address used by the region. The cbData member specifies the total size, in bytes, of the address space that is reserved for this region. The cbOverhead member specifies the size, in bytes, of the heap control structures that describe the region.  If this flag is set, the following members of this structure become valid: dwCommittedSize , dwUnCommittedSize, lpFirstBlock, and lpLastBlock. For further detail,. see the following description of each of these members.
PROCESS_HEAP_UNCOMMITTED_RANGE	If this flag is set, the heap element is located in a range of uncommitted memory within the heap region.  If this flag is set, the meanings of the following members of this structure change: The lpData member points to the beginning of the range of uncommitted memory. The cbData member specifies the size, in bytes, of the range of uncommitted memory. The cbOverhead member specifies the size, in bytes, of the control structures that describe this uncommitted range.
PROCESS_HEAP_ENTRY_BUSY	If this flag is set, the heap element is an allocated block.  If both this flag and the PROCESS_HEAP_ENTRY_MOVEABLE flag are set, the hMem member of this structure becomes valid, and contains a handle to the allocated, moveable memory block.
PROCESS_HEAP_ENTRY_MOVEABLE	This flag is only valid if the PROCESS_HEAP_ENTRY_BUSY flag is set, indicating that the heap element is an allocated block. If this flag is valid and set, the block was allocated with the LMEM_MOVEABLE or GMEM_MOVEABLE flag. The block is moveable. The hMem member of this structure becomes valid, and contains a handle to the allocated, moveable memory block.
PROCESS_HEAP_ENTRY_DDESHARE	This flag is only valid if the PROCESS_HEAP_ENTRY_BUSY flag is set, indicating that the heap element is an allocated block. If this flag is valid and set, the block was allocated with the GMEM_DDESHARE flag. For a discussion of the GMEM_DDESHARE flag, see GlobalAlloc .
dwCommittedSize

This member is valid only if the PROCESS_HEAP_REGION flag in wFlags is set. If the flag is not set, this member has no meaning.

If this member is valid, it specifies the number of bytes in the heap region that are currently committed as free memory blocks, busy memory blocks, or heap control structures.

This is an optional field that is set to zero if the number of committed bytes is not available.

dwUnCommittedSize

This member is valid only if the PROCESS_HEAP_REGION flag in wFlags is set. If the flag is not set, this member has no meaning.

If this member is valid, it specifies the number of bytes in the heap region that are currently uncommitted.

This is an optional field that is set to zero if the number of uncommitted bytes is not available.

lpFirstBlock

This member is valid only if the PROCESS_HEAP_REGION flag in wFlags is set. If the flag is not set, this member has no meaning.

If this member is valid, it points to the first valid memory block in this heap region.

lpLastBlock

This member is valid only if the PROCESS_HEAP_REGION flag in wFlags is set. If the flag is not set, this member has no meaning.

If this member is valid, it points to the first invalid memory block in this heap region.

hMem

This member is valid only if both the PROCESS_HEAP_ENTRY_BUSY and PROCESS_HEAP_ENTRY_MOVEABLE flags in wFlags are set. If the flags are not set, this member has no meaning.

If this member is valid, it contains a handle to the allocated, moveable memory block.

See Also

GlobalAlloc, HeapAlloc, HeapWalk


PROCESS_INFORMATION

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.

Members

hProcess

Returns a handle to the newly created process. The handle is used to specify the process in all functions that perform operations on the process object.

hThread

Returns a handle to the primary thread of the newly created process. The handle is used to specify the thread in all functions that perform operations on the thread object.

dwProcessId

Returns a global process identifier that can be used to identify a process. The value is valid from the time the process is created until the time the process is terminated.

dwThreadId

Returns a global thread identifiers that can be used to identify a thread. The value is valid from the time the thread is created until the time the thread is terminated.

See Also

CreateProcess


PROPSHEETHEADER  (preliminaryWindows NT)
PROPSHEETHEADER  (preliminary−Windows NT)

typedef struct _PROPSHEETHEADER { // psh

    DWORD      dwSize;

    DWORD      dwFlags;

    HWND       hwndParent;

    HINSTANCE  hInstance;

    union {

        HICON  hIcon;

        LPCTSTR pszIcon;

    };

    LPCTSTR     pszCaption;

    UINT       nPages

    union {

        UINT  nStartPage

        LPCTSTR pStartPage;

    };

    union {

        LPCPROPSHEETPAGE    ppsp;

        HPROPSHEETPAGE FAR *phpage;

    };

    PFNPROPSHEETCALLBACK pfnCallback;

} PROPSHEETHEADER, FAR *LPPROPSHEETHEADER;

typedef const PROPSHEETHEADER FAR *LPCPROPSHEETHEADER;

The PROPSHEETHEADER structure defines the frame and pages of a property sheet.

Members

dwSize

Size, in bytes, of this structure.

dwFlags

Array of flags that indicate which other members to use and which to ignore. This member can be a combination of the following values:

Value	Meaning
PSH_DEFAULT	Uses the default meaning for all structure members.
PSH_MULTILINETABS	Allows multiple rows of tabbed pages.
PSH_NOAPPLYNOW	Removes the Apply Now button.
PSH_PROPSHEETPAGE	Uses ppsp and ignores phpage when creating the pages for the property sheet.
PSH_PROPTITLE	Includes "Properties for" with the string specified by pszCaption in the title bar of the property sheet.
PSH_USECALLBACK	Calls the function specified by pfnCallback when initializing the property sheet defined by this structure.
PSH_USEHICON	Uses hIcon as the small icon in the title bar of the property sheet dialog box.
PSH_USEICONID	Uses pszIcon as the name of the icon resource to load and use as the small icon in the title bar of the property sheet dialog box.
PSH_USEPSTARTPAGE	Uses pStartPage and ignores nStartPage when displaying the initial page of the property sheet.
PSH_WIZARD	Creates a wizard property sheet.
hwndParent

Handle of the owner window.

hInstance

Handle of the instance from which to load the icon or title string resource. If pszIcon or pszCaption identifies a resource to load, this member must be specified.

hIcon

Handle of the icon to use as the small icon in the title bar of the property sheet dialog box. If dwFlags does not include the PSH_USEHICON value, this member is ignored.

pszIcon

Icon resource to use as the small icon in the title bar of the property sheet dialog box. This member can specify either the identifier of the icon resource or the pointer to the string that specifies the name of the icon resource. If dwFlags does not include the PSH_USEICONID value, this member is ignored.

pszCaption

Title of the property sheet dialog box. This member can specify either the identifier of a string resource or the pointer to a string that specifies the title. If dwFlags includes the PSH_PROPTITLE value, the string, "Properties for" is used with the title.

nPages

Number of elements in phpage array.

nStartPage

Zero-based index of the initial page that appears when the property sheet dialog box is created.

pStartPage

Name of the initial page that appears when the property sheet dialog box is created. This member can specify either the identifier of a string resource or the pointer to a string that specifies the name.

ppsp

Pointer to an array of PROPSHEETPAGE structures that define the pages in the property sheet. If dwFlags does not include the PSH_PROPSHEETPAGE value, this member is ignored.

phpage

Pointer to an array that contains handles of property sheet pages. Each handle must have been created by a previous call to the CreatePropertySheetPage function. If dwFlags includes the PSH_PROPSHEETPAGE value, this member is ignored.

pfnCallback

Pointer to an application-defined callback function that is called when the property sheet is initialized. For more information about the callback function, see the description of the PropSheetProc function. If dwFlags does not include the PSP_USECALLBACK value, this member is ignored.

See Also

CreatePropertySheetPage, PROPSHEETPAGE, PropSheetProc


PROPSHEETPAGE  (preliminaryWindows NT)
PROPSHEETPAGE  (preliminary−Windows NT)

typedef struct _PROPSHEETPAGE { // psp

    DWORD     dwSize;

    DWORD     dwFlags;

    HINSTANCE hInstance;

    union {

        LPCTSTR        pszTemplate;

        LPCDLGTEMPLATE pResource;

    };

    union {

        HICON  hIcon;

        LPCTSTR pszIcon;

    };

    LPCTSTR pszTitle;

    DLGPROC pfnDlgProc;

    LPARAM  lParam;

    LPFNPSPCALLBACK pfnCallback;

    UINT FAR * pcRefParent;

} PROPSHEETPAGE, FAR *LPPROPSHEETPAGE;

typedef const PROPSHEETPAGE FAR *LPCPROPSHEETPAGE;

The PROPSHEETPAGE structure defines a page in a property sheet.

Members

dwSize

Size, in bytes, of the structure. The size includes any extra application-defined data at the end of the structure.

dwFlags

Array of flags that indicate which other structure members to use and which to ignore. This member can be a combination of the following values:

Value	Meaning
PSP_DEFAULT	Uses the default meaning for all structure members.
PSP_DLGINDIRECT	Uses pResource instead of pszTemplate. That is, the template for the property sheet dialog box is supplied in memory, not loaded from a resource.
PSP_RTLREADING	Windows 95 only: Displays the text of pszTitle using right-to-left reading order on Hebrew or Arabic systems.
PSP_USECALLBACK	Calls the function specified by pfnCallback when creating or destroying the property sheet page defined by this structure.
PSP_USEHICON	Uses hIcon as the small icon on the tab for the page.
PSP_USEICONID	Uses pszIcon as the name of the icon resource to load and use as the small icon on the tab for the page.
PSP_USEREFPARENT	Maintains the reference count specified by pcRefParent for the lifetime of the property sheet page created from this structure.
PSP_USETITLE	Uses pszTitle as the title of the property sheet dialog box instead of the title stored in the dialog box template.
hInstance

Handle to the instance from which to load the dialog box template, icon, or title string resource.

pszTemplate

Dialog box template to use to create the page. This member can specify either the resource identifier of the template or the address of a string that specifies the name of the template. If dwFlags includes the PSP_DLGINDIRECT value, this member is ignored.

pResource

Pointer to a dialog box template in memory. If dwFlags does not include the PSP_DLGINDIRECT value, this member is ignored.

hIcon

Handle to the icon to use as the small icon in the tab for the page. If dwFlags does not include the PSP_USEHICON value, this member is ignored.

pszIcon

Icon resource to use as the small icon in the tab for the page. This member can specify either the identifier of the icon resource or the pointer to the string that specifies the name of the icon resource. If dwFlags does not include the PSP_USEICONID value, this member is ignored.

pszTitle

Title of the property sheet dialog box. This title overrides the title specified in the dialog box template. This member can specify either the identifier of a string resource or the pointer to a string that specifies the title. If dwFlags does not include the PSP_USETITLE value, this member is ignored.

pfnDlgProc

Pointer to the dialog box procedure for the page. The dialog box procedure must not call the EndDialog function.

lParam

Application-defined data.

pfnCallback

Pointer to an application-defined callback function that is called when the page is created and when it is about to be destroyed. For more information about the callback function, see PropSheetPageProc. If dwFlags does not include the PSP_USECALLBACK value, this member is ignored.

pcRefParent

Pointer to the reference count value. If dwFlags does not include the PSP_USERREFPARENT value, this member is ignored.

Remarks

When the PropertySheet function creates the page, the dialog box procedure for the page receives a WM_INITDIALOG message. The lParam parameter of this message points to the PROPSHEETPAGE structure used to create the page.

See Also

EndDialog, PropSheetPageProc, PropertySheet, WM_INITDIALOG


PROTOCOL_INFO

typedef  struct _PROTOCOL_INFO {

    DWORD  dwServiceFlags;

    INT  iAddressFamily;

    INT  iMaxSockAddr;

    INT  iMinSockAddr;

    INT  iSocketType;

    INT  iProtocol;

    DWORD  dwMessageSize;

    LPTSTR  lpProtocol;

} PROTOCOL_INFO;

The PROTOCOL_INFO structure contains information about a protocol.

Members

dwServiceFlags

A set of bit flags that specify the services provided by the protocol. One or more of the following bit flags may be set:

Value	Meaning
XP_CONNECTIONLESS	If this flag is set, the protocol providesconnectionless (datagram) service. If this flag is clear, the protocol provides connection-oriented data transfer.
XP_GUARANTEED_DELIVERY	If this flag is set, the protocol guarantees that all data sent will reach the intended destination. If this flag is clear, there is no such guarantee.
XP_GUARANTEED_ORDER	If this flag is set, the protocol guarantees that data will arrive in the order in which it was sent. Note that this characteristic does not guarantee delivery of the data, but guarantees only its order. If this flag is clear, the order of data sent is not guaranteed.
XP_MESSAGE_ORIENTED	If this flag is set, the protocol is message-oriented. A message-oriented protocol honors message boundaries. If this flag is clear, the protocol is stream-oriented, and the concept of message boundaries is irrelevant.
XP_PSEUDO_STREAM	If this flag is set, the protocol is a message-oriented protocol that ignores message boundaries for all receive operations.  This optional capability is useful when you do not want the protocol to frame messages. An application that requires stream-oriented characteristics can open a socket with type SOCK_STREAM for transport protocols that support this functionality, regardless of the value of iSocketType.
XP_GRACEFUL_CLOSE	If this flag is set, the protocol supports two-phase close operations, also known as "graceful" close operations. If this flag is clear, the protocol supports only abortive close operations.
XP_EXPEDITED_DATA	If this flag is set, the protocol supports expedited data, also known as "urgent data."
XP_CONNECT_DATA	If this flag is set, the protocol supports connect data.
XP_DISCONNECT_DATA	If this flag is set, the protocol supports disconnect data.
XP_SUPPORTS_BROADCAST	If this flag is set, the protocol supports a broadcast mechanism.
XP_SUPPORTS_MULTICAST	If this flag is set, the protocol supports a multicast mechanism.
XP_BANDWIDTH_ALLOCATION	If this flag is set, the protocol supports a mechanism for allocating a guaranteed bandwidth to an application.
XP_FRAGMENTATION	If this flag isset, the protocol supports message fragmentation; physical network MTU is hidden from applications.
XP_ENCRYPTS	If this flag is set, the protocol supports data encryption.
iAddressFamily

Specifies the value to pass as the af parameter when you call the socket function to open a socket for the protocol. This address family value uniquely defines the structure of Protocol addresses, also known as SOCKADDRs, used by the protocol.

iMaxSockAddr

Specifies the maximum length of a socket address supported by the protocol.

iMinSockAddr

Specifies the minimum length of a socket address supported by the protocol.

iSocketType

Specifies the value to pass as the type parameter when you call the socket function to open a socket for the protocol.

Note that if XP_PSEUDO_STREAM is set in dwServiceFlags, the application can specify SOCK_STREAM as the type parameter to socket, regardless of the value of iSocketType.

iProtocol

Specifies the value to pass as the protocol parameter when you call the socket function to open a socket for the protocol.

dwMessageSize

Specifies the maximum message size supported by the protocol. This is the maximum size of a message that can be sent from or received by the host. For protocols that do not support message framing, the actual maximum size of a message that can be sent to a given address may be less than this value.

The following special message size values are defined:

Value	Meaning
0	The protocol is stream-oriented; the concept of message size is not relevant.
0xFFFFFFFF	The protocol is message-oriented, but there is no maximum message size.
lpProtocol

Points to a zero-terminated string that supplies a name for the protocol; for example, "SPX2."

See Also

EnumProtocols, socket


PROVIDOR_INFO_1

typedef struct _PROVIDOR_INFO_1 { // pi1

    LPTSTR pName;

    LPTSTR pEnvironment ;

    LPTSTR pDLLName ;

} PROVIDOR_INFO_1;

The PROVIDOR_INFO_1 structure identifies a print provider.

Members

pName

Points to a null-terminated string that is the name of the print provider.

pEnvironment

Points to a null-terminated environment string specifying the environment the provider dynamic-link library (DLL) is designed to run in.

pDLLName

Points to a null-terminated string that is the name of the provider DLL.

See Also

MONITOR_INFO_2


PSHNOTIFY

typedef struct _PSHNOTIFY {
    NMHDR hdr;

    LPARAM lParam;

} PSHNOTIFY, FAR *LPPSHNOTIFY;

PSHNOTIFY contains information for the PSN_APPLY and PSN_RESET notification messages.

Members

hdr

Notification header.

lParam

Close flag. TRUE if the OK or Cancel button is used to close the property sheet. FALSE if the Close button used.

See Also

PSN_APPLY, PSN_RESET


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.

Members

dwServiceType

The value returned includes one of the following service type flags to indicate the type of service. In addition, for a SERVICE_WIN32 service, the SERVICE_INTERACTIVE_PROCESS flag might be set, indicating that the service process can interact with the desktop.

Value	Meaning
SERVICE_WIN32_OWN_PROCESS	A service type flag that indicates a Win32 service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS	A service type flag that indicates a Win32 service that shares a process with other services.
SERVICE_KERNEL_DRIVER	A service type flag that indicates a Windows NT device driver.
SERVICE_FILE_SYSTEM_DRIVER	A service type flag that indicates a Windows NT file system driver.
SERVICE_INTERACTIVE_PROCESS	A flag that indicates a Win32 service process that can interact with the desktop.
dwStartType

Specifies when to start the service. One of the following values is specified:

Value	Meaning
SERVICE_BOOT_START	Specifies a device driver started by the operating system loader. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_SYSTEM_START	Specifies a device driver started by the IoInitSystem function. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_AUTO_START	Specifies a device driver or Win32 service started by the service control manager automatically during system startup.
SERVICE_DEMAND_START	Specifies a device driver or Win32 service started by the service control manager when a process calls the StartService function.
SERVICE_DISABLED	Specifies a device driver or Win32 service that can no longer be started.
dwErrorControl

Specifies the severity of the error if this service fails to start during startup, and determines the action taken by the startup program if failure occurs. One of the following values can be specified:

Value	Meaning
SERVICE_ERROR_IGNORE
	The startup (boot) program logs the error but continues the startup operation.
SERVICE_ERROR_NORMAL
	The startup program logs the error and displays a message box pop-up but continues the startup operation.
SERVICE_ERROR_SEVERE
	The startup program logs the error. If the last-known good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.
SERVICE_ERROR_CRITICAL
	The startup program logs the error, if possible. If the last-known good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration.
lpBinaryPathName

Points to a null-terminated string that contains the fully qualified path to the service binary file.

lpLoadOrderGroup

Points to a null-terminated string that names the load ordering group of which this service is a member. If the pointer is NULL or if it points to an empty string, the service does not belong to a group. The registry has a list of load ordering groups located at:

HKEY_LOCAL_MACHINE\System
\CurrentControlSet\Control\ServiceGroupOrder.

The startup program uses this list to load groups of services in a specified order with respect to the other groups in the list. You can place a service in a group so that another service can depend on the group.

The order in which a service starts is determined by the following criteria:

1.	The order of groups in the registry's load-ordering group list. Services in groups in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list and then services that do not belong to a group.

2.	The service's dependencies listed in the lpszDependencies parameter and the dependencies of other services dependent on the service.

dwTagId

Specifies a unique tag value for this service in the group specified by the lpLoadOrderGroup parameter. A value of zero indicates that the service has not been assigned a tag. You can use a tag for ordering service startup within a load order group by specifying a tag order vector in the registry located at:

HKEY_LOCAL_MACHINE\System\CurrentControlSet
\Control\GroupOrderList

Tags are only evaluated for SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER type services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.

lpDependencies

Points to an array of null-separated names of services or load ordering groups that must start before this service. The array is doubly null-terminated. If the pointer is NULL or if it points to an empty string, the service has no dependencies. If a group name is specified, it must be prefixed by the SC_GROUP_IDENTIFIER (defined in the WINSVC.H file) character to differentiate it from a service name, because services and service groups share the same name space. Dependency on a service means that this service can only run if the service it depends on is running. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.

lpServiceStartName

Points to a null-terminated string. If the service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, this name is the account name in the form of "DomainName\Username", which the service process will be logged on as when it runs. If the account belongs to the built-in domain, ".\Username" can be specified. If NULL is specified, the service will be logged on as the LocalSystem account.

If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this name is the Windows NT driver object name (that is, \FileSystem\Rdr or \Driver\Xns) which the input and output (I/O) system uses to load the device driver. If NULL is specified, the driver is run with a default object name created by the I/O system based on the service name.

lpDisplayName

Points to a null-terminated string that is to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the service control manager. Display name comparisons are always case-insensitive.

Remarks

The configuration information for a service is initially specified when the service is created by a call to the CreateService function. The information can be modified by calling the ChangeServiceConfig function.

See Also

ChangeServiceConfig, CreateService, QueryServiceConfig, StartService


QUERY_SERVICE_LOCK_STATUS

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.

Members

fIsLocked

Specifies whether the database is locked. If this member is nonzero, the database is locked. If it is zero, the database is unlocked.

lpLockOwner

Points to a null-terminated string containing the name of the user who acquired the lock.

dwLockDuration

Specifies the time, in seconds, since the lock was first acquired.

See Also

QueryServiceLockStatus


RASAMB

typedef  struct  _RASAMB {

    DWORD    dwSize;

    DWORD    dwError;

    TCHAR    szNetBiosError[ NETBIOS_NAME_LEN + 1 ];

     BYTE     bLana;

} RASAMB;

The RASAMB structure contains the result of a remote access server (RAS) Authentication Message Block (AMB) projection operation.

The RasGetProjectionInfo function returns a RASAMB data structure when its rasprojection parameter has the value RASP_Amb.

Members

dwSize

Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to sizeof(RASAMB). The function can then determine the version of the RASAMB data structure that the caller of RasGetProjectionInfo is expecting. This allows backward compatibility for compiled applications if there are future enhancements to the data structure.

dwError

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

szNetBiosError

If dwError has the value ERROR_NAME_EXISTS_ON_NET, the szNetBiosError field contains a zero-terminated string that is the NetBIOS name that caused the conflict. For other values of dwError, this field contains the null string.

bLana

Identifies the NetBIOS network adapter identifier, or LANA, on which the remote access connection was established. This member contains the value 0xFF if a connection was not established.

Remarks

The AMB protocol is used with downlevel RAS servers. Windows NT 3.1 and OS/2 1.3, in relation to Windows NT 3.5, are downlevel RAS servers.

See Also

RasGetProjectionInfo, RASPROJECTION


RASCONN

typedef struct _RASCONN {

    DWORD     dwSize;

    HRASCONN  hrasconn;

    TCHAR     szEntryName[RAS_MaxEntryName + 1];

} RASCONN ;

The RASCONN structure provides information about a remote access connection. The RasEnumConnections function returns an array of RASCONN structures.

Members

dwSize

Specifies the size, in bytes, of the RASCONN structure.

hrasconn

Specifies the remote access connection. This handle is used in other remote access API calls.

szEntryName

A string that specifies the phone book entry used to establish the remote access connection. If the connection was established using an empty entry name, this string consists of a "." followed by the connection phone number.

See Also

RasEnumConnections, RasGetConnectStatus


RASCONNSTATUS

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 remote access connection. It is returned by the RasGetConnectStatus function.

Members

dwSize

Specifies the structure size, in bytes.

rasconnstate

Specifies a RASCONNSTATE enumerator value that indicates the current state of the RasDial connection process; that is, the piece of the RasDial process that is currently executing.

Two state values are especially significant:

State	Meaning
RASCS_Connected	Indicates that the connection has completed successfully.
RASCS_Disconnected	Indicates that the connection has failed.
dwError

If nonzero, indicates the reason for failure. The value is one of the error values from the RAS header file or one of ERROR_NOT_ENOUGH_MEMORY or ERROR_INVALID_HANDLE.

szDeviceType

A string that specifies the type of the current device, if available. For example, common device types supported by RAS 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


RASDIALEXTENSIONS

typedef  struct  _RASDIALEXTENSIONS {

    DWORD    dwSize;

    DWORD    dwfOptions;

    HWND    hwndParent;

    DWORD    reserved;

} RASDIALEXTENSIONS;

The RASDIALEXTENSIONS structure contains information about extended features of the RasDial function. You can enable one or more of these extensions by passing a pointer to a RASDIALEXTENSIONS structure when you call RasDial. If you do not pass a pointer to a RASDIALEXTENSIONS structure to RasDial, RasDial uses the default settings that are noted following.

Members

dwSize

Specifies the size of this structure, in bytes. Set this member to sizeof(RASDIALEXTENSIONS). This indicates the version of the structure.

dwfOptions

A set of bit flags that specify RasDial extensions. The following bit flags are defined; you must set all undefined bits to zero:

Value	Description
RDEOPT_UsePrefixSuffix	If this bit flag is one, RasDial uses the prefix and suffix that is in the RAS phonebook. If this bit flag is zero, RasDial ignores the prefix and suffix that is in the RAS phonebook. If no phonebook entry name is specified in the call to RasDial, the actual value of this bit flag is ignored, and it is assumed to be zero.
RDEOPT_PausedStates	If this bit flag is one, RasDial accepts paused states. Examples of paused states are terminal mode, retry logon, change password, and set callback number. If this bit flag is zero, RasDial reports a fatal error if it enters a paused state.
RDEOPT_IgnoreModemSpeaker	If this bit flag is one, RasDial ignores the modem speaker setting that is in the RAS phonebook, and uses the setting specified by the RDEOPT_SetModemSpeaker bit flag. If this bit flag is zero, RasDial uses the modem speaker setting that is in the RAS phonebook, and ignores the setting specified by the RDEOPT_SetModemSpeaker bit flag. If no phonebook entry name is specified in the call to RasDial, the choice is between using a default setting or the setting specified by the RDEOPT_SetModemSpeaker bit flag. The default setting is used if RDEOPT_IgnoreModemSpeaker is zero. The setting specified by RDEOPT_SetModemSpeaker is used if RDEOPT_IgnoreModemSpeaker is one.
RDEOPT_SetModemSpeaker	If this bit flag is one, and RDEOPT_IgnoreModemSpeaker is one, RasDial sets the modem speaker on.  If this bit flag is zero, and RDEOPT_IgnoreModemSpeaker is one, RasDial sets the modem speaker off. If RDEOPT_IgnoreModemSpeaker is zero, RasDial ignores the value of RDEOPT_SetModemSpeaker, and sets the modem speaker based on the RAS phonebook setting or the default setting.
RDEOPT_IgnoreSoftwareCompression	If this bit flag is one, RasDial ignores the software compression setting that is in the RAS phonebook, and uses the setting specified by the RDEOPT_SetSoftwareCompression bit flag. If this bit flag is zero, RasDial uses the software compression setting that is in the RAS phonebook, and ignores the setting specified by the RDEOPT_SetSoftwareCompression bit flag. If no phonebook entry name is specified in the call to RasDial, the choice is between using a default setting or the setting specified by the RDEOPT_SetSoftwareCompression bit flag. The default setting is used if RDEOPT_IgnoreSoftwareCompression is zero. The setting specified by RDEOPT_SetSoftwareCompression is used if RDEOPT_IgnoreSoftwareCompression is one.
RDEOPT_SetSoftwareCompression	If this bit flag is one, and RDEOPT_IgnoreSoftwareCompression is one, RasDial uses software compression.  If this bit flag is zero, and RDEOPT_IgnoreSoftwareCompression is one, RasDial does not use software compression. If RDEOPT_IgnoreSoftwareCompression is zero, RasDial ignores the value of RDEOPT_SetSoftwareCompression, and sets the software compression state based on the RAS phonebook setting or the default setting.
The default value for each of these bit flags is zero.

hwndParent

Handle to a parent window that a security DLL can use for dialog box creation and centering.

Note that this is not the window that receives RasDial progress notifications.

This member is optional; it is not required when no security DLL is defined.

The default value for this member is NULL.

reserved

This member is reserved for future use. It must be set to zero.

See Also

RasDial


RASDIALPARAMS

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 remote access connection.

Members

dwSize

Specifies the structure size, in bytes.

szEntryName

Specifies a string containing the phone book entry to use to establish the connection. An empty string ("") specifies a simple modem connection on the first available modem port, in which case a non-empty szPhoneNumber must be provided.

szPhoneNumber

Specifies a string containing an overriding phone number. An empty string ("") indicates that the phone book entry's phone number should be used. If szEntryName is "", szPhoneNumber cannot be "".

szCallbackNumber

Specifies a string containing a callback phone number. An empty string ("") indicates that callback should not be used. This string is ignored unless the user has "Set By Caller" callback permission on the RAS server. An asterisk indicates that the number stored in the phone book should be used for callback.

szUserName

Specifies a string containing the user's user name. This string is used to authenticate the user's access to the remote access server.

szPassword

Specifies a string containing the user's password. This string is used to authenticate the user's access to the remote access server.

szDomain

Specifies a string containing the domain on which authentication is to occur. An empty string ("") specifies the domain in which the remote access server is a member. An asterisk specifies the domain stored in the phone book for the entry.

Remarks

The szUserName and szPassword strings are used only 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 user name and password of the currently logged-on user for authentication.

See Also

RasDial


RASENTRYNAME

typedef struct _RASENTRYNAME {

    DWORD  dwSize;

    TCHAR  szEntryName[RAS_MaxEntryName + 1];

}RASENTRYNAME;

•	The RASENTRYNAME structure contains an entry name from a remote access phone book created by RASPHONE.EXE. The RasEnumEntries function returns an array of these structures.

Members

dwSize

Specifies the structure size, in bytes.

szEntryName

Specifies a string containing the entry name as entered in an "Entry name" field in RASPHONE.EXE.

See Also

RasEnumEntries


RASPPPIP

typedef  struct  _RASPPPIP {

    DWORD    dwSize;

    DWORD    dwError;

    TCHAR    szIpAddress[ RAS_MaxIpAddress + 1 ];

} RASPPPIP;

The RASPPPIP structure contains the result of a PPP Internet Protocol (IP) projection operation.

The RasGetProjectionInfo function returns a RASPPPIP data structure when its rasprojection parameter has the value RASP_PppIp.

Members

dwSize

Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to indicate the version of the RASPPPIP structure that you are using. For information about earlier versions of this structure, see the following Remarks section.

dwError

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

szIpAddress

Contains a zero-terminated string that is the client's IP address on the RAS connection. This address string has the form a.b.c.d; for example, "11.101.237.71".

szServerIpAddress

Contains a null-terminated string that is the IP address of the remote PPP peer (that is, the server's IP address). This string is in "a.b.c.d" form. PPP does not require that servers provide this address, but Windows NT servers will consistently return the address anyway. Other PPP vendors may not provide the address. If the address is not available, this member returns an empty string, "".

Remarks

The szServerIpAddress member was added to the RASPPPIP structure beginning with Windows NT 3.51 and the initial release of Windows 95. Beginning with these systems, RasGetProjectionInfo will support both the current form of the structure and the old form without the szServerIpAddress member. Use the dwSize member to indicate which version you are using.

For earlier versions of Windows NT, RasGetProjectionInfo will return ERROR_INVALID_SIZE if dwSize specifies the current structure size. To retrieve PPP IP information from older systems, dwSize must specify the size of the old structure without the szServerIpAddress member.

See Also

RasGetProjectionInfo, RASPROJECTION


RASPPPIPX

typedef  struct  _RASPPPIPX {

    DWORD    dwSize;

    DWORD    dwError;

    TCHAR    szIpxAddress[ RAS_MaxIpxAddress + 1 ];

} RASPPPIPX;

The RASPPPIPX structure contains the result of a PPP Internetwork Packet Exchange (IPX) projection operation.

The RasGetProjectionInfo function returns a RASPPPIPX data structure when its rasprojection parameter has the value RASP_PppIpx.

Members

dwSize

Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to sizeof(RASPPPIPX). The function can then determine the version of the RASPPPIPX data structure that the caller of RasGetProjectionInfo is expecting. This allows backwards compatibility for compiled applications if there are future enhancements to the data structure.

dwError

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

szIpxAddress

Contains a zero-terminated string that is the client's IPX address on the RAS connection. This address string has the form net.node; for example, "1234ABCD.12AB34CD56EF".

See Also

RasGetProjectionInfo, RASPROJECTION


RASPPPNBF

typedef  struct  _RASPPPNBF {

    DWORD    dwSize;

    DWORD    dwError;

    DWORD    dwNetBiosError;

    TCHAR    szNetBiosError[ NETBIOS_NAME_LEN + 1 ];

    TCHAR    szWorkstationName[ NETBIOS_NAME_LEN + 1 ];

     BYTE     bLana;

} RASPPPNBF;

The RASPPPNBF structure contains the result of a PPP NetBEUI Framer (NBF) projection operation.

The RasGetProjectionInfo function returns a RASPPPNBF data structure when its rasprojection parameter has the value RASP_PppNbf.

Members

dwSize

Specifies the size of the structure, in bytes. Before calling the RasGetProjectionInfo function, set this member to sizeof(RASPPPNBF). The function can then determine the version of the RASPPPNBF data structure that the caller of RasGetProjectionInfo is expecting. This allows backwards compatibility for compiled applications if there are future enhancements to the data structure.

dwError

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

dwNetBiosError

If dwError has the value ERROR_SERVER_NOT_RESPONDING or ERROR_NETBIOS_ERROR, the dwNetBiosError field contains the NetBIOS error that occurred. For other values of dwError, this field contains zero.

szNetBiosError

If dwError has the value ERROR_NAME_EXISTS_ON_NET, the szNetBiosError field contains a zero-terminated string that is the NetBIOS name that caused the conflict. For other values of dwError, this field contains the null string.

szWorkStationName

Contains a zero-terminated string that is the local workstation's computer name. This unique computer name is the closest NetBIOS equivalent to a client's NetBEUI address on a remote access connection.

bLana

Identifies the NetBIOS network adapter identifier, or LANA, on which the remote access connection was established. This member contains the value 0xFF if a connection was not established.

See Also

RasGetProjectionInfo, RASPROJECTION


RASTERIZER_STATUS

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.

Members

nSize

Specifies the size, in bytes, of the RASTERIZER_STATUS structure.

wFlags

Specifies whether at least one TrueType font is installed and whether TrueType is enabled. This value is TT_AVAILABLE, TT_ENABLED, or both if TrueType is on the system.

nLanguageID

Specifies the language in the system's SETUP.INF file.

See Also

GetRasterizerCaps


REASSIGN_BLOCKS

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.

Members

Reserved

This member is reserved. Do not use it. Set it to zero.

Count

Specifies the number of blocks to be reassigned. This is the number of elements that are in the BlockNumber member array.

BlockNumber

An array of Count block numbers, one for each block to be reassigned.

Remarks

The DeviceIoControl function uses a REASSIGN_BLOCKS structure as input to an IOCTL_DISK_REASSIGN_BLOCKS device input and output control operation.

See Also

DeviceIoControl, IOCTL_DISK_REASSIGN_BLOCKS


RECT

typedef struct _RECT {    // 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.

Members

left

Specifies the x-coordinate of the upper-left corner of the rectangle.

top

Specifies the y-coordinate of the upper-left corner of the rectangle.

right

Specifies the x-coordinate of the lower-right corner of the rectangle.

bottom

Specifies the y-coordinate of the lower-right corner of the rectangle.

Remarks

When RECT is passed to the FillRect function, the rectangle is filled up to, but not including, the right column and bottom row of pixels. This structure is identical to the RECTL structure.

See Also

FillRect, RECTL, SMALL_RECT


RECTL

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.

Members

left

Specifies the x-coordinate of the upper-left corner of the rectangle.

top

Specifies the y-coordinate of the upper-left corner of the rectangle.

right

Specifies the x-coordinate of the lower-right corner of the rectangle.

bottom

Specifies the y-coordinate of the lower-right corner of the rectangle.

Remarks

When RECTL is passed to the FillRect function, the rectangle is filled up to, but not including, the right column and bottom row of pixels. This structure is identical to the RECT structure.

See Also

FillRect, RECT, SMALL_RECT


REMOTE_NAME_INFO

typedef struct _REMOTE_NAME_INFO { /* rni */

    LPTSTR  lpUniversalName;

    LPTSTR  lpConnectionName;

    LPTSTR  lpRemainingPath;

} REMOTE_NAME_INFO;

The REMOTE_NAME_INFO data structure contains path and name information about a network resource. The structure contains a member that points to a Universal Naming Convention (UNC) name string for the resource, and two members that point to additional network connection information strings.

Members

lpUniversalName

Points to a zero-terminated UNC name string.

lpConnectionName

Points to a zero-terminated string that is the name of a network connection.

lpRemainingPath

Points to a zero-terminated UNC name string.

Remarks

The REMOTE_NAME_INFO data structure contains a pointer to a Universal Naming Convention (UNC) name string. UNC names look like this:

\\servername\sharename\path\file

You can pass the REMOTE_NAME_INFO structure's lpConnectionName member to the WNetAddConnection2 function as the lpRemoteName member of the NETRESOURCE structure pointed to by lpNetResource. This lets you connect a local device to a network resource. You can then append the string pointed to by the lpRemainingPath member to the local device string, and pass the resulting string to Win32 functions that use a drive-based path.

See Also

WNetAddConnection2, UNIVERSAL_NAME_INFO


REQRESIZE  (preliminaryWindows NT)
REQRESIZE  (preliminary−Windows NT)

typedef struct _reqresize {

    NMHDR nmhdr;

    RECT rc;

} REQRESIZE;

The REQRESIZE structure contains the requested size of a rich edit control. A rich edit control sends this structure to its parent window as part of an EN_REQUESTRESIZE notification message.

Members

nmhdr

Notification header.

rc

Requested new size.

See Also

EN_REQUESTRESIZE


RGBQUAD

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.

Members

rgbBlue

Specifies the intensity of blue in the color.

rgbGreen

Specifies the intensity of green in the color.

rgbRed

Specifies the intensity of red in the color.

rgbReserved

Reserved; must be zero.

Remarks

The bmiColors member of the BITMAPINFO structure consists of an array of RGBQUAD structures.

See Also

BITMAPINFO, CreateDIBitmap, CreateDIBSection, GetDIBits, SetDIBits, SetDIBitsToDevice, StretchDIBits


RGBTRIPLE

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.

Members

rgbtBlue

Specifies the intensity of blue in the color.

rgbtGreen

Specifies the intensity of green in the color.

rgbtRed

Specifies the intensity of red in the color.

See Also

BITMAPCOREINFO


RGNDATA

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. The rectangles are sorted top to bottom, left to right. They do not overlap.

Members

rdh

Specifies a RGNDATAHEADER structure. The members of this structure specify the type of region (whether it is rectangular or trapezoidal), the number of rectangles that make up the region, the size of the buffer that contains the rectangle structures, and so on.

Buffer

Specifies an arbitrary-size buffer that contains the RECT structures that make up the region.

See Also

RECT, RGNDATAHEADER


RGNDATAHEADER

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.

Members

dwSize

Specifies the size, in bytes, of the header.

iType

Specifies the type of region. This value must be RDH_RECTANGLES.

nCount

Specifies the number of rectangles that make up the region.

nRgnSize

Specifies the size of the buffer required to receive the RECT structure that specifies the coordinates of the rectangles that make up the region. If the size is not known, this member can be zero.

rcBound

Specifies a bounding rectangle for the region.

See Also

GetRegionData, RECT, RGNDATA


RIP_INFO

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.

dwError

Specifies the error that caused the RIP debug event.

dwType

Specifies additional information about the type of error that caused the RIP debug event. This may be one of the following values:

Value	Meaning
SLE_ERROR	Indicates that invalid data was passed to the function that failed. This caused the application to fail.
SLE_MINORERROR	Indicates that invalid data was passed to the function, but the error probably will not cause the application to fail.
SLE_WARNING	Indicates that potentially invalid data was passed to the function, but the function completed processing.
0	Indicates that only dwError was set.
See Also

DEBUG_EVENT


SCROLLINFO  (preliminaryWindows NT)
SCROLLINFO

typedef struct tagSCROLLINFO {  // si

    UINT cbSize;

    UINT fMask;

    int  nMin;

    int  nMax;

    UINT nPage;

    int  nPos;

    int  nTrackPos;

}   SCROLLINFO;

typedef SCROLLINFO FAR *LPSCROLLINFO;

The SCROLLINFO structure contains scroll bar parameters to be set by the SetScrollInfo function (or SBM_SETSCROLLINFO message), or retrieved by the GetScrollInfo function (or SBM_GETSCROLLINFO message).

cbSize

Specifies the size, in bytes, of this structure.

fMask

Specifies the scroll bar parameters to set or retrieve. This member can be a combination of the following values:

Value	Meaning
SIF_ALL	Combination of SIF_PAGE, SIF_POS, and SIF_RANGE.
SIF_DISABLENOSCROLL	This value is used only when setting a scroll bar's parameters. If the scroll bar's new parameters make the scroll bar unnecessary, disable the scroll bar instead of removing it.
SIF_PAGE	The nPage member contains the page size for a proportional scroll bar.
SIF_POS	The nPos parameter contains the scroll box position.
SIF_RANGE	The nMin and nMax members contain the minimum and maximum values for the scrolling range.
nMin

Specifies the minimum scrolling position.

nMax

Specifies the maximum scrolling position.

nPage

Specifies the page size. A scroll bar uses this value to determine the appropriate size of the proportional scroll box.

nPos

Specifies the position of the scroll box.

nTrackPos

Specifies the immediate position of a scroll box that the user is dragging. An application can retrieve this value while processing the SB_THUMBTRACK notification message. An application cannot set the immediate scroll position; the SetScrollInfo function ignores this member.

See Also

SBM_GETSCROLLINFO, SBM_SETSCROLLINFO, GetScrollInfo, SetScrollInfo


SECURITY_ATTRIBUTES

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.

Members

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.

Remarks

A pointer to a SECURITY_ATTRIBUTES structure is used as a parameter in most kernel and window-management functions in the Win32 API that return a handle of an object.

See Also

SECURITY_DESCRIPTOR


SECURITY_DESCRIPTOR

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.

Remarks

A security descriptor includes information that specifies the following components of an object's security:

•	An owner (SID)

•	A primary group (SID)

•	A discretionary ACL

•	A system ACL

•	Qualifiers for the preceding items

Security descriptors use access-control lists (ACLs) and security identifiers (SIDs) to specify the information in this list.

A security descriptor can be in absolute or self-relative form. In self-relative form, all members of the structure are located contiguously in memory. In absolute form, the structure only contains pointers to the members.

See Also

GetSecurityDescriptorControl, GetSecurityDescriptorDacl, GetSecurityDescriptorGroup, GetSecurityDescriptorLength, GetSecurityDescriptorOwner, GetSecurityDescriptorSacl, InitializeSecurityDescriptor, IsValidSecurityDescriptor, SetSecurityDescriptorDacl, SetSecurityDescriptorGroup, SetSecurityDescriptorOwner, SetSecurityDescriptorSacl


SECURITY_DESCRIPTOR_CONTROL

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


SECURITY_INFORMATION

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_QUALITY_OF_SERVICE

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.

Members

Length

Specifies the size, in bytes, of this structure.

ImpersonationLevel

Specifies what the server may be told about the client, and how the server may represent, or impersonate, the client. Security impersonation levels govern the degree to which a server process can act on behalf of a client process. This member is a SECURITY_IMPERSONATION_LEVEL enumeration type value.

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


SELCHANGE  (preliminaryWindows NT)
SELCHANGE  (preliminary−Windows NT)

typedef struct _selchange {

    NMHDR nmhdr;

    CHARRANGE chrg;

    WORD seltyp;

} SELCHANGE;

The SELCHANGE stucture contains information associated with an EN_SELCHANGE notification message. A rich edit control sends this notification to its parent window when the current selection changes.

Members

nmhdr

Notification header.

chrg

New selection range.

seltyp

Value specifying the contents of the new selection. This member is SEL_EMPTY if the selection is empty or one or more of the following values:

Value	Contents of the selection
SEL_TEXT	Text
SEL_OBJECT	At least one OLE object
SEL_MULTICHAR	More than one character of text
SEL_MULTIOBJECT	More than one OLE object
See Also

EN_SELCHANGE


SERIALKEYS  (preliminaryWindows NT)
SERIALKEYS  (preliminary−Windows NT)

typedef struct tagSERIALKEYS {     // sk

    DWORD cbSize;

    DWORD dwFlags;

    LPSTR lpszActivePort;

    LPSTR lpszPort;

    DWORD iBaudRate;

    DWORD iPortState;

} SERIALKEYS, FAR* LPSERIALKEYS;

The SERIALKEYS structure contains information about the SerialKeys accessibility feature, which interprets data from a communication aid attached to a serial port as commands causing the system to simulate keyboard and mouse input.

Members

cbSize

Specifies the structure size, in bytes.

dwFlags

Specifies a combination of the following values:

Value	Meaning
SERKF_ACTIVE	The SerialKeys feature is currently receiving input on the serial port specified by lpszPort.
SERKF_AVAILABLE	The SerialKeys feature is available.
SERKF_INDICATOR	A visual indicator is displayed when the SerialKeys feature is on. This value is not currently used and is ignored.
SERKF_SERIALKEYSON	The SerialKeys feature is on.
lpszActivePort

Points to a string that contains the name of the serial port that receives input from the communication aid when the SerialKeys feature is on. If no port is being used, this member is NULL. If this member is "Auto", the system watches all unused serial ports for input from communication aids.

lpszPort

Reserved; must be NULL.

iBaudRate

Specifies the baud rate setting for the serial port specified by the lpszActivePort member. This member should be set to one of the CBR_ values defined in the Windows header files. If lpszActivePort is NULL, this member is zero.

iPortState

Specifies the state of the port specified by the lpszActivePort member. If lpszActivePort is NULL, iPortState is zero; otherwise, it is one of the following values:

Value	Meaning
0	All input on this port is ignored by the SerialKeys feature.
1	Input on this port is watched for SerialKeys activation sequences when no other application has the port open.
2	All input on this port is treated as SerialKeys commands.
Remarks

An application uses this structure when calling the SystemParametersInfo function with the SPI_GETSERIALKEYS or SPI_SETSERIALKEYS value. When using SPI_GETSERIALKEYS, an application must specify the cbSize, lpszActivePort, and lpszPort members of the SERIALKEYS structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SPI_SETSERIALKEYS value.

See Also

SystemParametersInfo


SERVICE_ADDRESS
SERVICE_ADDRESS  [image]  (preliminary−Windows NT)

typedef struct _SERVICE_ADDRESS {

    DWORD   dwAddressType;

    DWORD   dwAddressFlags;

    DWORD   dwAddressLength;

    DWORD   dwPrincipalLength;

    BYTE   *lpAddress;

    BYTE   *lpPrincipal;

} SERVICE_ADDRESS;

The SERVICE_ADDRESS structure contains address information for a service. The structure can accomodate many types of interprocess communications (IPC) mechanisms and their address forms, including remote procedure calls (RPCs), named pipes, and sockets.

Members

dwAddressType

Specifies the address family that the socket address pointed to by lpAddress belongs to.

dwAddressFlags

A set of bit flags that specify properties of the address. The following bit flags are defined:

Value	Meaning
SERVICE_ADDRESS_FLAG_RPC_CN	If this bit flag is set, the service supports connection-oriented RPC over this transport protocol.
SERVICE_ADDRESS_FLAG_RPC_DG	If this bit flag is set, the service supports datagram-oriented RPC over this transport protocol.
SERVICE_ADDRESS_FLAG_RPC_NB	If this bit flag is set, the service supports NetBIOS RPC over this transport protocol.
dwAddressLength

Specifies the size, in bytes, of the address.

dwPrincipalLength

This member is reserved for future use. It must be zero.

lpAddress

Points to a socket address of the appropriate type.

lpPrincipal

This member is reserved for future use. It must be NULL.

See Also

SERVICE_ADDRESSES, SERVICE_INFO


SERVICE_ADDRESSES
SERVICE_ADDRESSES  [image]  (preliminary−Windows NT)

typedef struct _SERVICE_ADDRESSES {

    DWORD   dwAddressCount;

    SERVICE_ADDRESS   Addresses[1];

} SERVICE_ADDRESSES;

The SERVICE_ADDRESSES structure contains an array of SERVICE_ADDRESS data structures.

Members

dwAddressCount

Specifies the number of SERVICE_ADDRESS structures in the Addresses array.

Addresses

An array of SERVICE_ADDRESS data structures. Each SERVICE_ADDRESS structure contains information about a network service address.

See Also

SERVICE_ADDRESS, SERVICE_INFO


SERVICE_INFO
SERVICE_INFO  [image]  (preliminary−Windows NT)

typedef struct _SERVICE_INFO {

    LPGUID   lpServiceType;

    LPTSTR   lpServiceName;

    LPTSTR   lpComment;

    LPTSTR   lpLocale;

    DWORD    dwDisplayHint;

    DWORD    dwVersion;

    DWORD    dwTime;

    LPTSTR   lpMachineName;

    LPSERVICE_ADDRESSES lpServiceAddress;

    BLOB ServiceSpecificInfo;

} SERVICE_INFO;

The SERVICE_INFO structure contains information about a network service or a network service type.

Members

lpServiceType

Points to a GUID that is the type of the network service.

lpServiceName

Points to a zero-terminated string that is the name of the network service.

If you are calling the SetService function with the dwNameSpace parameter set to NS_DEFAULT, the network service name must be a common name A common name is what the network service is commonly known as. An example of a common name for a network service is "My SQL Server".

If you are calling the SetService function with the dwNameSpace parameter set to a specific service name, the network service name can be a common name or a distinguished name. A distinguished name distinguishes the service to a unique location with a directory service. An example of a distinguished name for a network service is "MS\\SYS\\NT\\DEV\\My SQL Server". The

lpComment

Points to a zero-terminated string that is a comment or description for the network service. For example, "Used for development upgrades."

lpLocale

Points to a zero-terminated string that contains locale information.

dwDisplayHint

Specifies a hint as to how to display the network service in a network browsing user interface. This can be one of the following values:

Value	Meaning
RESOURCEDISPLAYTYPE_DOMAIN	Display the network service as a domain.
RESOURCEDISPLAYTYPE_FILE	Display the network service as a file.
RESOURCEDISPLAYTYPE_GENERIC	The method used to display the object does not matter.
RESOURCEDISPLAYTYPE_GROUP	Display the network service as a group.
RESOURCEDISPLAYTYPE_SERVER	Display the network service as a server.
RESOURCEDISPLAYTYPE_SHARE	Display the network service as a sharepoint.
RESOURCEDISPLAYTYPE_TREE	Display the network service as a tree.
dwVersion

Specifies version information for the network service. The high word of this value specifies a major version number. The low word of this value specifies a minor version number.

dwTime

This member is reserved for future use. It must be set to zero.

lpMachineName

Points to a zero-terminated string that is the name of the computer on which the network service is running.

lpServiceAddress

Points to a SERVICE_ADDRESSES structure that contains an array of SERVICE_ADDRESS structures. Each SERVICE_ADDRESS structure contains information about a network service address.

A network service can call the getsockname function to determine the local address of the system.

ServiceSpecificInfo

A BLOB structure that specifies service-defined information.

Note that, in general, the data pointed to by the BLOB structure's pBlobData member must not contain any pointers. That is because only the network service knows the format of the data; copying the data without such knowledge would lead to pointer invalidation. If the data pointed to by pBlobData contains variable-sized elements, offsets from pBlobData can be used to indicate the location of those elements. There is one exception to this general rule: when pBlobData points to a SERVICE_TYPE_INFO_ABS structure. This is possible because both the SERVICE_TYPE_INFO_ABS structure, and any SERVICE_TYPE_VALUE_ABS structures it contains are predefined, and thus their formats are known to the operating system.

See Also

BLOB, GetService, NS_SERVICE_INFO, SetService, SERVICE_ADDRESS, SERVICE_ADDRESSES, SERVICE_TYPE_INFO_ABS, SERVICE_TYPE_VALUE_ABS


SERVICE_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.

Members

dwServiceType

The value returned includes one of the following service type flags to indicate the type of service. In addition, for a SERVICE_WIN32 service, the SERVICE_INTERACTIVE_PROCESS flag might be set, indicating that the service process can interact with the desktop.

Value	Meaning
SERVICE_WIN32_OWN_PROCESS	A service type flag that indicates a Win32 service that runs in its own process.
SERVICE_WIN32_SHARE_PROCESS	A service type flag that indicates a Win32 service that shares a process with other services.
SERVICE_KERNEL_DRIVER	A service type flag that indicates a Windows NT device driver.
SERVICE_FILE_SYSTEM_DRIVER	A service type flag that indicates a Windows NT file system driver.
SERVICE_INTERACTIVE_PROCESS	A flag that indicates a Win32 service process that can interact with the desktop.
dwCurrentState

Indicates the current state of the service. One of the following values is specified:

Value	Meaning
SERVICE_STOPPED	The service is not running.
SERVICE_START_PENDING	The service is starting.
SERVICE_STOP_PENDING	The service is stopping.
SERVICE_RUNNING	The service is running.
SERVICE_CONTINUE_PENDING	The service continue is pending.
SERVICE_PAUSE_PENDING	The service pause is pending.
SERVICE_PAUSED	The service is paused.
dwControlsAccepted

Specifies the control codes that the service will accept and process. A user interface process can control a service by specifying a control command in the ControlService function. By default, all services accept the SERVICE_CONTROL_INTERROGATE value. Any or all of the following flags can be specified to enable the other control codes.

Value	Meaning
SERVICE_ACCEPT_STOP
	The service can be stopped. This enables the SERVICE_CONTROL_STOP value.
SERVICE_ACCEPT_PAUSE_CONTINUE
	The service can be paused and continued. This enables the SERVICE_CONTROL_PAUSE and SERVICE_CONTROL_CONTINUE values.
SERVICE_ACCEPT_SHUTDOWN
	The service is notified when system shutdown occurs. This enables the system to send a SERVICE_CONTROL_SHUTDOWN value to the service. The ControlService function cannot send this control code.
dwWin32ExitCode

Specifies a Win32 error code that the service uses to report an error that occurs when it is starting or stopping. To return an error code specific to the service, the service must set this value to ERROR_SERVICE_SPECIFIC_ERROR to indicate that the dwServiceSpecificExitCode member contains the error code. The service should set this value to NO_ERROR when it is running and on normal termination.

dwServiceSpecificExitCode

Specifies a service specific error code that the service returns when an error occurs while the service is starting or stopping. This value is ignored unless the dwWin32ExitCode member is set to ERROR_SERVICE_SPECIFIC_ERROR.

dwCheckPoint

Specifies a value that the service increments periodically to report its progress during a lengthy start, stop, or continue operation. For example, the service should increment this value as it completes each step of its initialization when it is starting up. The user interface program that invoked the operation on the service uses this value to track the progress of the service during a lengthy operation. This value is not valid and should be zero when the service does not have a start, stop, or continue operation pending.

dwWaitHint

Specifies an estimate of the amount of time, in milliseconds, that the service expects a pending start, stop, or continue operation to take before the service makes its next call to the SetServiceStatus function with either an incremented dwCheckPoint value or a change in dwCurrentState. If the amount of time specified by dwWaitHint passes, and dwCheckPoint has not been incremented, or dwCurrentState has not changed, the service control manager or service control program can assume that an error has occurred.

See Also

ControlService, EnumDependentServices, EnumServicesStatus, QueryServiceStatus, SetServiceStatus


SERVICE_TABLE_ENTRY
SERVICE_TABLE_ENTRY  [image]  (preliminary−Windows NT)

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.

Members

lpServiceName

Points to a null-terminated string that names a service that can run in this service process. This string is ignored if the service is installed in the service control manager database as a SERVICE_WIN32_OWN_PROCESS service type. For a SERVICE_WIN32_SHARE_PROCESS service process, this string names the service that uses the ServiceMain function pointed to by the lpServiceProc member.

lpServiceProc

Points to a ServiceMain function.

See Also

ServiceMain, StartServiceCtrlDispatcher


SERVICE_TYPE_INFO_ABS
SERVICE_TYPE_INFO_ABS  [image]  (preliminary−Windows NT)

typedef struct _SERVICE_TYPE_INFO_ABS {

    LPTSTR                  lpTypeName;

    DWORD                   dwValueCount;

    SERVICE_TYPE_VALUE_ABS  Values[1];

} SERVICE_TYPE_INFO_ABS

The SERVICE_TYPE_INFO_ABS structure contains information about a network service type. You use a SERVICE_TYPE_INFO_ABS structure to add a network service type to a name space.

Members

lpTypeName

Points to a zero-terminated string that is the name of the network service type.  This name is the same in all name spaces, and is used by the GetTypeByName and GetNameByType functions.

dwValueCount

Specifies the number of SERVICE_TYPE_VALUE_ABS structures in the Values member array that follows dwValueCount.

Values[1]

An array of SERVICE_TYPE_VALUE_ABS structures.

Each of these structures contains information about a service type value that the operating system or network service may need when an instance of this network service type is registered with a name space.

The information in these structures may be specific to a name-space. For example, if a network service uses the SAP name space, but does not have a GUID that contains the SAP identifier (SAPID), it defines the SAPID in a SERVICE_TYPE_VALUE_ABS structure.

Remarks

When you use the SetService function to add a network service type to a name space, the SERVICE_TYPE_INFO_ABS structure is passed as the ServiceSpecificInfo BLOB member of a SERVICE_INFO structure. Although the ServiceSpecificInfo member generally should not contain pointers, an exception is made in the case of the SERVICE_TYPE_INFO_ABS and SERVICE_TYPE_VALUE_ABS structures.

See Also

SetService, SERVICE_INFO, SERVICE_TYPE_VALUE_ABS


SERVICE_TYPE_VALUE_ABS
SERVICE_TYPE_VALUE_ABS  [image]  (preliminary−Windows NT)

typedef struct _SERVICE_TYPE_VALUE_ABS {

    DWORD   dwNameSpace;

    DWORD   dwValueType;

    DWORD   dwValueSize;

    LPTSTR  lpValueName;

    PVOID   lpValue;

} SERVICE_TYPE_VALUE_ABS

The SERVICE_TYPE_VALUE_ABS structure contains information about a network-service type value. This information may be specific to a name space.

Members

dwNameSpace

Specifies the name space, or a set of default name spaces, for which the network service type value is intended . Name-space providers will look only at values intended for their name space.

Use one of the following constants to specify a name space:

Value	Name Space
NS_DEFAULT	A set of default name spaces. The function queries each name space within this set. The set of default name spaces typically includes all the name spaces installed on the system. System administrators, however, can exclude particular name spaces from the set. NS_DEFAULT is the value that most applications should use for dwNameSpace.
NS_DNS	The Domain Name System used in the Internet for host name resolution.
NS_NETBT	The NetBIOS over TCP/IP layer. All Windows NT systems register their computer names with NetBIOS. This name space is used to convert a computer name to an IP address that uses this registration. Note that NS_NETBT may access a WINS server to perform the resolution.
NS_SAP	The Netware Service Advertising Protocol. This may access the Netware bindery if appropriate. NS_SAP is a dynamic name space that allows registration of services.
NS_TCPIP_HOSTS	Lookup value in the <systemroot>\system32\drivers\etc\hosts file.
NS_TCPIP_LOCAL	Local TCP/IP name resolution mechanisms, including comparisons against the local host name and looks up host names and IP addresses in cache of host to IP address mappings.
dwValueType

Specifies the type of the value data. You can specify one of the following types:

Value	Meaning
REG_BINARY	Binary data in any form.
REG_DWORD	A 32-bit number.
REG_MULTI_SZ	An array of null-terminated strings, terminated by two null characters.
REG_SZ	A null-terminated string.
dwValueSize

Specifies the size, in bytes, of the value data. In the case of REG_SZ and REG_MULTI_SZ string data, the terminating characters are counted as part of the size.

lpValueName

Points to a zero-terminated string that is the name of the value. This name is specific to a name space.

Several commonly used value name strings are associated with defined constants. These name strings include the following:

Constant	Name String
SERVICE_TYPE_VALUE_SAPID	"SapId"
SERVICE_TYPE_VALUE_CONN	"ConnectionOriented"
SERVICE_TYPE_VALUE_TCPPORT	"TcpPort"
SERVICE_TYPE_VALUE_UDPPORT	"UdpPort"
lpValue

Points to the value data.

Remarks

When you use the SetService function to add a network service type to a name space, a SERVICE_TYPE_INFO_ABS structure is passed as the ServiceSpecificInfo BLOB member of a SERVICE_INFO structure. Although the ServiceSpecificInfo member generally should not contain pointers, an exception is made in the case of the SERVICE_TYPE_INFO_ABS and SERVICE_TYPE_VALUE_ABS structures.

See Also

SetService, SERVICE_INFO, SERVICE_TYPE_INFO_ABS


SESSION_BUFFER

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 the NCBSSTAT command in the ncb_command member of the NCB structure.

Members

lsn

Specifies the local session number.

state

Specifies the state of the session. This member can be one of the following values:

Value	Meaning
LISTEN_OUTSTANDING	The session is waiting for a call from a remote computer.
CALL_PENDING	The session is attempting to connect to a remote computer.
SESSION_ESTABLISHED	The session connected and is able to transfer data.
HANGUP_PENDING	The session is being deleted due to a command by the local user.
HANGUP_COMPLETE	The session was deleted due to a command by the local user.
SESSION_ABORTED	The session was abandoned due to a network or user problem.
local_name

Specifies the 16-byte NetBIOS name on the local computer used for this session.

remote_name

Specifies the 16-byte NetBIOS name on the remote computer used for this session.

rcvs_outstanding

Specifies the number of pending NCBRECV commands.

sends_outstanding

Specifies the number of pending NCBSEND and NCBCHAINSEND commands.

See Also

NCB, SESSION_HEADER


SESSION_HEADER

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.

Members

sess_name

Specifies the name number of the session. This value corresponds to the ncb_num member of the NCB structure.

num_sess

Specifies the number of sessions that have the name specified by the sess_name member.

rcv_dg_outstanding

Specifies the number of outstanding NCBDGRECV and NCBDGRECVBC commands.

rcv_any_outstanding

Specifies the number of outstanding NCBRECVANY commands.

See Also

NCB, SESSION_BUFFER


SET_PARTITION_INFORMATION
SET_PARTITION_INFORMATION  [image]  (preliminary−Windows NT)

typedef struct _SET_PARTITION_INFORMATION {

   BYTE PartitionType;

} SET_PARTITION_INFORMATION ;

The SET_PARTITION_INFORMATION structure provides information used to set a disk partition's type.

Members

PartitionType

Specifies the type of partition. This member can be one of the following values:

Value	Meaning
PARTITION_ENTRY_UNUSED	Entry unused.
PARTITION_FAT_12	Specifies a partition with 12-bit FAT entries.
PARTITION_XENIX_1	Specifies a Xenix type 1 partition.
PARTITION_XENIX_2	Specifies a Xenix type 2 partition.
PARTITION_FAT_16	Specifies a partition with 16-bit FAT entries.
PARTITION_EXTENDED	Specifies an extended partition entry.
PARTITION_HUGE	Specifies an MS-DOS V4 huge partition.
PARTITION_IFS	Specifies an IFS partition.
PARTITION_UNIX	Specifies a Unix partition.
VALID_NTFT	Specifies an NTFT partition.
Remarks

The DeviceIoControl function uses a SET_PARTITION_INFORMATION structure as input to an IOCTL_DISK_SET_PARTITION_INFO device input and output control operation.

See Also

DeviceIoControl, IOCTL_DISK_GET_PARTITION_INFO, IOCTL_DISK_SET_PARTITION_INFO, PARTITION_INFORMATION


SHCONTF

typedef enum tagSHCONTF {

    SHCONTF_FOLDERS = 32,         // for shell browser

    SHCONTF_NONFOLDERS = 64,      // for default view

    SHCONTF_INCLUDEHIDDEN = 128,  // for hidden or system objects

} SHCONTF;

Specifies an enumerated type that defines flags used with the IShellFolder::EnumObjects method.

See Also

IShellFolder::EnumObjects


SHFILEINFO

typedef struct _SHFILEINFO { // shfi

    HICON hIcon;                   // see below

    int   iIcon;                   // see below

    DWORD dwAttributes;            // see below

    char  szDisplayName[MAX_PATH]; // see below

    char  szTypeName[80];          // see below

} SHFILEINFO;

Contains information about a file object.

Members

hIcon

Handle of the icon that represents the file.

iIcon

Index of the icon image within the system image list.

dwAttributes

Array of flags that indicates the attributes of the file object. For information about the flags, see the description of the IShellFolder::GetAttributesOf method.

szDisplayName

String that contains the name of the file as it appears in the Windows shell, or path and filename of the file that contains the icon representing the file.

szTypeName

String that describes the type of the file.

Remarks

This structure is used with the SHGetFileInfo function.

See Also

IShellFolder::GetAttributesOf, SHGetFileInfo


SHFILEOPSTRUCT

typedef struct _SHFILEOPSTRUCT { // shfos

    HWND         hwnd;                  // see below

    UINT         wFunc;                 // see below

    LPCSTR       pFrom;                 // see below

    LPCSTR       pTo;                   // see below

    FILEOP_FLAGS fFlags;                // see below

    BOOL         fAnyOperationsAborted; // see below

    LPVOID       hNameMappings;         // see below

    LPCSTR       lpszProgressTitle;     // see below

} SHFILEOPSTRUCT, FAR *LPSHFILEOPSTRUCT;

Contains information that the SHFileOperation function uses to perform file operations.

Members

hwnd

Handle of the dialog box to use to display information about the status of the operation. If fFlags includes the FOF_CREATEPROGRESSDLG value, this parameter is the handle of the parent window for the progress dialog box created by the system.

wFunc

Operation to perform. This member can be one of the following values:

FO_COPY	Copies the files specified by pFrom to the location specified by pTo.
FO_DELETE	Deletes the files specified by pFrom (pTo is ignored).
FO_MOVE	Moves the files specified by pFrom to the location specified by pTo.
FO_RENAME	Renames the files specified by pFrom.
pFrom

Pointer to a string that contains the names of the source files.

pTo

Pointer to a string that specifies the destination for the moved, copied, or renamed file.

fFlags

Flags that control the file operation. This member can be a combination of the following values:

FOF_ALLOWUNDO	Preserves undo information, if possible.
FOF_CONFIRMMOUSE	Not implemented.
FOF_FILESONLY	Performs the operation only on files if a wildcard filename (*.*) is specified.
FOF_MULTIDESTFILES	Indicates that the pTo member specifies multiple destination files (one for each source file) rather than one directory where all source files are to be deposited.
FOF_NOCONFIRMATION	Responds with "yes to all" for any dialog box that is displayed.
FOF_NOCONFIRMMKDIR	Does not confirm the creation of a new directory if the operation requires one to be created.
FOF_RENAMEONCOLLISION	Gives the file being operated on a new name (such as "Copy #1 of...") in a move, copy, or rename operation if a file of the target name already exists.
FOF_SILENT	Does not display a progress dialog box.
FOF_SIMPLEPROGRESS	Displays a progress dialog box, but does not show the filenames.
FOF_WANTMAPPINGHANDLE	Fills in the hNameMappings member. The handle must be freed by using the SHFreeNameMappings function.
fAnyOperationsAborted

Value that receives TRUE if the user aborted any file operations before they were completed or FALSE otherwise.

hNameMappings

Handle of a filename mapping object that contains an array of SHNAMEMAPPING structures. Each structure contains the old and new path names for each file that was moved, copied, or renamed. This member is used only if fFlags includes FOF_WANTMAPPINGHANDLE.

lpszProgressTitle

Pointer to a string to use as the title for a progress dialog box. This member is used only if fFlags includes FOF_SIMPLEPROGRESS.

Remarks

If pFrom or pTo are unqualified names, the current directories are taken from the global current drive and directory settings as managed by the GetCurrentDirectory and SetCurrentDirectory functions.

The SHGetNameMappingPtr macro retrieves a pointer to the filename mapping object returned in the hNameMappings member. The SHGetNameMappingCount macro retrieves the number of SHNAMEMAPPING structures in the object.

See Also

GetCurrentDirectory, SetCurrentDirectory, SHFileOperation, SHFreeNameMappings, SHGetNameMappingPtr, SHGetNameMappingCount, SHNAMEMAPPING


SHGNO

typedef enum tagSHGDN {

    SHGDN_NORMAL = 0,           // see below

    SHGDN_INFOLDER = 1,         // see below

    SHGDN_FORPARSING = 0x8000,  // see below

} SHGNO;

Specifies an enumerated type that defines flags used with the IShellFolder::GetDisplayNameOf and IShellFolder::SetNameOf methods.

Members

SHGDN_NORMAL

Default display name that is suitable for a file object displayed by itself, as shown in the following examples.

File system path	Corresponding display name
C:\WINDOWS\FILE.TXT	file
\\COMPUTER\SHARE	share on computer
C:\ (where drive C has the volume name My Drive)	My Drive (C)
SHGDN_INFOLDER

Display name that is suitable for a file object displayed within its respective folder, as shown in the following examples.

File system path	Corresponding display name
C:\WINDOWS\FILE.TXT	file
\\COMP\SHARE	user
C:\ (where drive C has the volume name My Drive)	My Drive (C)
SHGDN_FORPARSING

Display name that can be passed to the ParseDisplayName method of the parent folder's IShellFolder object.

File system path	Corresponding display name
C:\WINDOWS\FILE.TXT	C:\WINDOWS\FILE.TXT
\\COMP\SHARE	\\COMP\SHARE
C:\ (where drive C has the volume name My Drive)	C:\
See Also

IShellFolder::GetDisplayNameOf, IShellFolder::SetNameOf, ParseDisplayName


SHITEMID

typedef struct _SHITEMID {       // mkid

    USHORT cb;       // size of identifier, including cb itself

    BYTE   abID[1];  // variable length item identifier

} SHITEMID, * LPSHITEMID;

typedef const SHITEMID  * LPCSHITEMID;

Defines an item identifier.


SHNAMEMAPPING

typedef struct _SHNAMEMAPPING { // shnm

    LPSTR pszOldPath; // address of old path name

    LPSTR pszNewPath; // pointer to new path name

    int   cchOldPath; // number of characters in old path name

    int   cchNewPath; // number of characters in new path name

} SHNAMEMAPPING, FAR *LPSHNAMEMAPPING;

Contains the old and new path names for each file that was moved, copied, or renamed by the SHFileOperation function.

See Also

SHFileOperation


SID

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

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.

Members

Sid

Points to a SID structure.

Attributes

Specifies attributes of the SID. This value contains up to 32 one-bit flags. Its meaning depends on the definition and use of the SID.

Remarks

A group is represented by a SID. SIDs have attributes that indicate whether they are currently enabled, disabled, or mandatory, and how they are used. A SID_AND_ATTRIBUTES structure can represent a SID whose attributes change frequently. For example, it is used to represent groups in the TOKEN_GROUPS structure.

See Also

SID, TOKEN_GROUPS, TOKEN_USER


SID_IDENTIFIER_AUTHORITY

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).

Members

Value

An array of six bytes specifying a SID's top-level authority.

Remarks

The identifier authority value identifies the agency that issued the SID. Some identifier authorities are predefined:

Identifier authority	Value
SECURITY_NULL_SID_AUTHORITY	0
SECURITY_WORLD_SID_AUTHORITY	1
SECURITY_LOCAL_SID_AUTHORITY	2
SECURITY_CREATOR_SID_AUTHORITY	3
SECURITY_NT_AUTHORITY	5
A SID must contain a top-level authority and at least one relative identifier (RID) value.

See Also

AllocateAndInitializeSid, GetSidIdentifierAuthority, InitializeSid, SID


SINGLE_LIST_ENTRY

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.

Members

Next

Points to the next entry in a single-linked list.

Remarks

This structure can be used as the beginning of a single-linked list or as any subsequent entry in the list.


SIZE

typedef struct tagSIZE { // siz

    LONG cx;

    LONG cy;

} SIZE;

The SIZE structure specifies the width and height of a rectangle.

Members

cx

Specifies the rectangle's width.

cy

Specifies the rectangle's height.

Remarks

The rectangle dimensions stored in this structure may correspond to viewport extents, window extents, text extents, bitmap dimensions, or the aspect-ratio filter for some extended functions.

See Also

GetAspectRatioFilterEx, GetBitmapDimensionEx, GetTextExtentPoint32, GetViewportExtEx, GetWindowExtEx, ScaleViewportExtEx, ScaleWindowExtEx, SetBitmapDimensionEx, SetViewportExtEx, SetWindowExtEx


SMALL_RECT

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.

Members

Left

Specifies the x-coordinate of the upper left corner of the rectangle.

Top

Specifies the y-coordinate of the upper left corner of the rectangle.

Right

Specifies the x-coordinate of the lower right corner of the rectangle.

Bottom

Specifies the y-coordinate of the lower right corner of the rectangle.

Remarks

This structure is used by console functions to specify rectangular areas of console screen buffers, where the coordinates specify the rows and columns of screen-buffer character cells.

See Also

RECT, RECTL


SOUNDSENTRY

typedef struct tagSOUNDSENTRY {     // ss

    UINT cbSize;

    DWORD dwFlags;

    DWORD iFSTextEffect;

    DWORD iFSTextEffectMSec;

    DWORD iFSTextEffectColorBits;

    DWORD iFSGrafEffect;

    DWORD iFSGrafEffectMSec;

    DWORD iFSGrafEffectColor;

    DWORD iWindowsEffect;

    DWORD iWindowsEffectMSec;

    LPTSTR lpszWindowsEffectDLL;

    DWORD iWindowsEffectOrdinal;

} SOUNDSENTRY, *LPSOUNDSENTRY;

The SOUNDSENTRY structure contains information about the SoundSentry accessibility feature. When the SoundSentry feature is on, the computer displays a visual indication only when a sound is generated.

Windows 95: The visual indication is displayed when a sound is generated through the computer's internal speaker.

Windows NT The visual indication is displayed when a sound is generated through either the multimedia sound services or through the computer's speaker.

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

A set of bit flags that specify properties of the SoundSentry feature. The following bit-flag values are defined:

Value	Meaning
SSF_AVAILABLE	If this flag is set, the SoundSentry feature is available.
SSF_SOUNDSENTRYON	If this flag is set, the SoundSentry feature is on.
iFSTextEffect

Windows 95: Specifies the visual signal to present when a text-mode application generates a sound while running in a full-screen virtual machine. This member can be one of the following values:

Value	Meaning
SSTF_BORDER	Flash the screen border (that is, the overscan area), which is unavailable on some displays.
SSTF_CHARS	Flash characters in the corner of the screen.
SSTF_DISPLAY	Flash the entire display.
SSTF_NONE	No visual signal.

Windows NT: This member is reserved for future use. It must be set to zero.

iFSTextEffectMSec

Windows 95: Specifies the duration, in milliseconds, of the visual signal that is displayed when a full-screen, text-mode application generates a sound.

Wndows NT: This member is reserved for future use. It must be set to zero.

iFSTextEffectColorBits

Windows 95: Specifies the RGB value of the color to be used when displaying the visual signal shown when a full-screen, text-mode application generates a sound.

Windows NT: This member is reserved for future use. It must be set to zero.

iFSGrafEffect

Windows 95: Specifies the visual signal to present when a graphics-mode application generates a sound while running in a full-screen virtual machine. This member can be one of the following values:

Value	Meaning
SSGF_DISPLAY	No visual signal.
SSGF_NONE	Flash the entire display.

Windows NT: This member is reserved for future use. It must be set to zero.

iFSGrafEffectMSec

Windows 95: Specifies the duration, in milliseconds, of the visual signal that is displayed when a full-screen, graphics-mode application generates a sound.

Windows NT: This member is reserved for future use. It must be set to zero.

iFSGrafEffectColor

Windows 95: Specifies the RGB value of the color to be used when displaying the visual signal shown when a full-screen, graphics-mode application generates a sound.

Windows NT: This member is reserved for future use. It must be set to zero.

iWindowsEffect

Specifies the visual signal to display when a sound is generated by a Windows-based application or an MS-DOS application running in a window. This member can be one of the following values:

Value	Meaning
SSWF_CUSTOM	Windows 95 only: Call the SoundSentryProc routine exported by the DLL specified by the iFSWindowsEffectDLL member.
SSWF_DISPLAY	Flash the entire display.
SSWF_NONE	No visual signal.
SSWF_TITLE	Flash the title bar of the active window.
SSWF_WINDOW	Flash the active window.
iWindowsEffectMSec

Windows 95: Specifies the duration, in milliseconds, of the visual signal that is displayed when a Windows-based application (or a non-Windows-based application running in a window) generates a sound.

Windows NT: This member is reserved for future use. It must be set to zero.

lpszWindowsEffectDLL

Windows 95: Points to the buffer that contains the name of the DLL that contains a SoundSentryProc callback function. The length of the name must not exceed the value of MAX_PATH. This member is NULL if no DLL is used. When retrieving information about the SoundSentry feature, the size of the buffer must be equal to, or larger than, the value of MAX_PATH.

Windows NT: This member is reserved for future use. It must be set to NULL.

iWindowsEffectOrdinal

This member is reserved for future use on both platforms. It must be set to zero.

Remarks

An application uses a SOUNDSENTRY structure when calling the SystemParametersInfo function with the wAction parameter set to SPI_GETSOUNDSENTRY or SPI_SETSOUNDSENTRY. When using SPI_GETSOUNDSENTRY, an application must specify the cbSize member of the SOUNDSENTRY structure; the SystemParametersInfo function fills the remaining members. An application must specify the cbSize, dwFlags, and iWindowsEffect members when using the SPI_SETSOUNDSENTRY value.

See Also

SoundSentryProc, SystemParametersInfo


STARTUPINFO

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 with the CreateProcess function to specify main window properties if a new window is created for the new process. For graphical user interface (GUI) processes, this information affects the first window created by the CreateWindow function. For console processes, this information affects the console window if a new console is created for the process. A process can use the GetStartupInfo function to retrieve the STARTUPINFO structure specified when the process was created.

Members

cb

Specifies the size, in bytes, of the structure.

lpReserved

Reserved. Set this member to NULL before passing the structure to CreateProcess.

lpDesktop

Windows 95: Ignore this member.

Windows NT: Points to a zero-terminated string that specifies either the name of the desktop only or the name of both the window station and desktop for this process. A backslash in the string pointed to by lpDesktop indicates that the string includes both desktop and window station names. Otherwise, the lpDesktop string is interpreted as a desktop name. If lpDesktop is NULL, the new process inherits the window station and desktop of its parent process.

lpTitle

For console processes, this is the title displayed in the title bar if a new console window is created. If NULL, the name of the executable file is used as the window title instead. This parameter must be NULL for GUI or console processes that do not create a new console window.

dwX, dwY

Ignored unless dwFlags specifies STARTF_USEPOSITION. Specifies the x and y offsets, in pixels, of the upper left corner of a window if a new window is created. The offsets are from the upper left corner of the screen. For GUI processes, the specified position is used the first time the new process calls CreateWindow to create an overlapped window if the x parameter of CreateWindow is CW_USEDEFAULT.

dwXSize, dwYSize

Ignored unless dwFlags specifies STARTF_USESIZE. Specifies the width (dwXSize) and height (dwYSize), in pixels, of the window if a new window is created. For GUI processes, this is used only the first time the new process calls CreateWindow to create an overlapped window if the nWidth parameter of CreateWindow is CW_USEDEFAULT.

dwXCountChars, dwYCountChars

Ignored unless dwFlags specifies STARTF_USECOUNTCHARS. For console processes, if a new console window is created, dwXCountChars specifies the screen buffer width in character columns, and dwYCountChars specifies the screen buffer height in character rows. These values are ignored in GUI processes.

dwFillAttribute

Ignored unless dwFlags specifies STARTF_USEFILLATTRIBUTE. 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 this value is not specified, the wShowWindow member is ignored.
STARTF_USEPOSITION	If this value is not specified, the dwX and dwY members are ignored.
STARTF_USESIZE	If this value is not specified, the dwXSize and dwYSize members are ignored.
STARTF_USECOUNTCHARS	If this value is not specified, the dwXCountChars and dwYCountChars members are ignored.
STARTF_USEFILLATTRIBUTE	If this value is not specified, the dwFillAttribute member is ignored.
STARTF_FORCEONFEEDBACK	If this value is specified, the cursor is in feedback mode for two seconds after CreateProcess is called. If during those two seconds the process makes the first GUI call, the system gives five more seconds to the process. If during those five seconds the process shows a window, the system gives five more seconds to the process to finish drawing the window.
	The system turns the feedback cursor off after the first call to GetMessage, regardless of whether the process is drawing.
	For more information on feedback, see the following Remarks section.
STARTF_FORCEOFFFEEDBACK	If specified, the feedback cursor is forced off while the process is starting. The normal cursor is displayed. For more information on feedback, see the following Remarks section.
STARTF_SCREENSAVER	If specified, the system will treat the application as a screen saver:
	• The system allows the application to initialize at the foreground priority of the priority class passed to the CreateProcess function.
	• When the application checks for input using 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 presses 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 this value is specified, sets the standard input of the process, standard output, and standard error handles to the handles specified in the hStdInput, hStdOutput, and hStdError members of the STARTUPINFO structure. The CreateProcess function's fInheritHandles parameter must be set to TRUE for this to work properly.
	If this value is not specified, the hStdInput, hStdOutput, and hStdError members of the STARTUPINFO structure are ignored.
wShowWindow

Ignored unless dwFlags specifies STARTF_USESHOWWINDOW. For GUI processes, wShowWindow specifies the default value the first time ShowWindow is called, if the nCmdShow parameter of ShowWindow is SW_SHOWDEFAULT. The wshowWindow member can be any of the SW_ constants defined in WINUSER.H.

In earlier 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 STARTUPINFO structure of the process.

cbReserved2

Reserved; must be zero.

lpReserved2

Reserved; must be NULL.

hStdInput

Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the standard input handle of the process if STARTF_USESTDHANDLES is specified.

hStdOutput

Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the standard output handle of the process if STARTF_USESTDHANDLES is specified.

hStdError

Ignored unless dwFlags specifies STARTF_USESTDHANDLES. Specifies a handle that will be used as the standard error handle of the process if STARTF_USESTDHANDLES is specified.

Remarks

If a GUI process is being started and neither STARTF_FORCEONFEEDBACK or STARTF_FORCEOFFFEEDBACK is specified, the process feedback cursor is used. A GUI process is one whose subsystem is specified as "windows."

See Also

CreateProcess, CreateWindow, GetMessage, GetStartupInfo, PeekMessage, ShowWindow, WinMain


STICKYKEYS

typedef struct tagSTICKYKEYS {     // sk

    DWORD cbSize;

    DWORD dwFlags;

} STICKYKEYS, *LPSTICKYKEYS;

The STICKYKEYS structure contains information about the StickyKeys accessibility feature. When the StickyKeys feature is on, the user can press a modifier key (SHIFT, CTRL, or ALT) and then another key in sequence rather than at the same time, to enter shifted (modified) characters and other key combinations.

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

A set of bit-flags that specify properties of the StickyKeys feature. The following bit-flag values are defined:

Value	Meaning
SKF_AUDIBLEFEEDBACK	If this flag is set, the system plays a sound when the user latches, locks, or releases modifier keys using the StickyKeys feature.
SKF_AVAILABLE	If this flag is set, the StickyKeys feature is available.
SKF_CONFIRMHOTKEY	Windows 95 only: A confirmation dialog appears when the StickyKeys feature is activated by using the hot key.
SKF_HOTKEYACTIVE	If this flag is set, the user can turn the StickyKeys feature on and off by pressing the SHIFT key five times.
SKF_HOTKEYSOUND	If this flag is set, the system plays a siren sound when the user turns the StickyKeys feature on or off by using the hot key.
SKF_INDICATOR	Windows 95 only: A visual indicator should be displayed when the StickyKeys feature is on.
SKF_STICKYKEYSON	If this flag is set, the StickyKeys feature is on.
SKF_TRISTATE	If this flag is set, pressing a modifier key twice in a row locks down the key until the user presses it a third time.
SKF_TWOKEYSOFF	If this flag is set, releasing a modifier key that has been pressed in combination with any other key turns off the StickyKeys feature.
Remarks

An application uses a STICKYKEYS structure when calling the SystemParametersInfo function with the wAction parameter set to SPI_GETSTICKYKEYS or SPI_SETSTICKYKEYS. When using SPI_GETSTICKYKEYS, an application must specify the cbSize member of the STICKYKEYS structure; the SystemParametersInfo function fills the remaining members. You must specify all structure members when using the SPI_SETSTICKYKEYS value.

See Also

SystemParametersInfo


STRRET

typedef struct _STRRET { // str

    UINT uType; // see below

    union

    {

        LPWSTR pOleStr;        // pointer to OLE string to free

        UINT   uOffset;        // offset into item identifier list

        char   cStr[MAX_PATH]; // buffer to receive the display name

    } DUMMYUNIONNAME;

} STRRET, *LPSTRRET;

Contains strings returned from IShellFolder methods, such as GetDisplayNameOf.

Member

uType

Value that specifies the desired format of the string. This member can be one of the following values:

STRRET_CSTR	The string is returned in cStr.
STRRET_OFFSET	The string is located at uOffset bytes from the beginning of the item identifier list.
STRRET_WSTR	The string is at the address pointed to by pOleStr.
Remarks

The system may or may not provide the display name in the desired format. When IShellFolder::GetDisplayNameOf returns, the uType member indicates the format.

See Also

IShellFolder::GetDisplayNameOf


String

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.

Members

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−1994".
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.

Remarks

A String structure may have an szKey value of, for example, "CompanyName" and a Value of "Microsoft Corporation". Another String structure with the same szKey value could contain a Value of "Microsoft GmbH". This might occur if the second String structure were associated with a StringTable structure whose szKey value is 04070000 — that is, German/ASCII.

See Also

StringTable, VS_FIXEDFILEINFO, VS_VERSION_INFO


StringFileInfo

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.

Members

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 Children structures. Each StringTable structure's szKey member indicates the appropriate language and code-page formatting.

Remarks

The Children member of the VS_VERSION_INFO structure may contain zero or more StringFileInfo structures.

See Also

StringTable, VS_VERSION_INFO


StringTable

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.

Members

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.

Remarks

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

StringFileInfo, VS_VERSION_INFO


STYLEBUF  (preliminaryWindows 95)
STYLEBUF  (preliminary−Windows 95)

typedef struct _tagSTYLEBUF {
    DWORD  dwStyle;
    CHAR  szDescription[32];
} STYLEBUF;

The STYLEBUF structure contains the identifier and name of a style.

Members

dwStyle

Style of the register string. Can be IME_REGWORD_STYLE_EUDC to indicate a string in the EUDC range.

szDescription

Description of the style.


STYLESTRUCT

typedef struct tagSTYLESTRUCT {  // ss

    DWORD styleOld;

    DWORD styleNew;

} STYLESTRUCT, * LPSTYLESTRUCT;

The STYLESTRUCT structure contains the window styles for a window.

Members

style

Specifies an array of window style or extended-style flags.

See Also

WM_STYLECHANGED, WM_STYLECHANGING


SYSTEM_ALARM_ACE

Reserved for future use.


SYSTEM_AUDIT_ACE

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).

Members

Header

Specifies an ACE_HEADER structure.

Mask

Specifies an ACCESS_MASK structure that gives the access rights causing audit messages to be generated. The SUCCESSFUL_ACCESS_ACE_FLAG and FAILED_ACCESS_ACE_FLAG flags in the AceFlags member of the ACE_HEADER structure indicate whether messages are generated for successful access attempts, unsuccessful access attempts, or both.

SidStart

Specifies a SID. An access attempt of a kind specified by the Mask member by any user or group whose SID matches the SidStart member causes the system to generate an audit message. If an application does not specify a SID for this member, audit messages are generated for the specified access rights for all users and groups.

Remarks

Audit messages are stored in an event log that can be manipulated by using the Win32 API event-logging functions or by using Windows NT Event Viewer (EVENTVWR.EXE).

ACE structures should be aligned on doubleword boundaries. All Windows memory-management functions return doubleword-aligned handles to memory.

See Also

ACCESS_ALLOWED_ACE, ACCESS_DENIED_ACE, ACCESS_MASK, ACE_HEADER, ACL, SYSTEM_ALARM_ACE


SYSTEM_INFO

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.

Members

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.

Windows 95: The following processor type constants are currently defined and can be returned:

PROCESSOR_INTEL_386
PROCESSOR_INTEL_486
PROCESSOR_INTEL_PENTIUM_586

Windows NT: The following processor type constants are currently defined and can be returned:

PROCESSOR_ALPHA_21064
PROCESSOR_ALPHA_21164

PROCESSOR_INTEL_386
PROCESSOR_INTEL_486
PROCESSOR_INTEL_PENTIUM_586
PROCESSOR_INTEL_860

PROCESSOR_MIPS_R2000
PROCESSOR_MIPS_R3000
PROCESSOR_MIPS_R4000

PROCESSOR_PPC_601
PROCESSOR_PPC_603
PROCESSOR_PPC_604
PROCESSOR_PPC_620

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


SYSTEM_POWER_STATUS  (preliminaryWindows 95)
SYSTEM_POWER_STATUS  (preliminary−Windows 95)

typedef struct _SYSTEM_POWER_STATUS {
    BYTE ACLineStatus;
    BYTE  BatteryFlag;
    BYTE  BatteryLifePercent;
    BYTE  Reserved1;
    DWORD  BatteryLifeTime;
    DWORD  BatteryFullLifeTime;
} SYSTEM_POWER_STATUS;
typedef struct SYSTEM_POWER_STATUS *LPSYSTEM_POWER_STATUS;

The SYSTEM_POWER_STATUS structure contains information about the power status of the system.

Members

ACLineStatus

AC power status. This parameter can be one of the following values:

Value	Meaning
0	Offline
1	Online
255	Unknown status.
All other values are reserved.

BatteryFlag

Battery charge status. This parameter can be a combination of the following values:

Value	Meaning
1	High
2	Low
4	Critical
8	Charging
128	No system battery
255	Unknown status
All other values are reserved.

BatteryLifePercent

Percentage of full battery charge remaining. This member can be a value in the range 0 to 100, or 255 if status is unknown. All other values are reserved.

Reserved1

Reserved; must be zero.

BatteryLifeTime

Number of seconds of battery life remaining, or 0xFFFFFFFF if remaining seconds are unknown.

BatteryFullLifeTime

Number of seconds of battery life when at full charge, or 0xFFFFFFFF if full lifetime is unknown.


SYSTEMTIME

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.

Members

wYear

Specifies the current year.

wMonth

Specifies the current month; January = 1, February = 2, and so on.

wDayOfWeek

Specifies the current day of the week; Sunday = 0, Monday = 1, and so on.

wDay

Specifies the current day of the month.

wHour

Specifies the current hour.

wMinute

Specifies the current minute.

wSecond

Specifies the current second.

wMilliseconds

Specifies the current millisecond.

See Also

GetLocalTime, GetSystemTime, SetLocalTime, SetSystemTime, FILETIME


TAPE_ERASE

typedef struct _TAPE_ERASE { // ter

    ULONG Type;

} TAPE_ERASE;

The TAPE_ERASE structure describes the partition to be erased.

Members

Type

Specifies how to erase the tape. This member must have one of the following values:

Value	Description
TAPE_ERASE_LONG	Erases the entire partition.
TAPE_ERASE_SHORT	Erases only the partition's header block.


TAPE_GET_DRIVE_PARAMETERS

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.

Members

ECC

Specifies whether the device supports hardware error correction. This member is TRUE if hardware error correction is supported.

Compression

Specifies whether hardware data compression is enabled or disabled. This member is TRUE if hardware data compression is enabled.

DataPadding

Specifies whether data padding is enabled or disabled. Data padding keeps the tape streaming at a constant speed. This member is TRUE if data padding is enabled.

ReportSetmarks

Specifies whether setmark reporting is enabled or disabled. This member is TRUE if setmark reporting is enabled.

DefaultBlockSize

Specifies the device's default fixed block size.

MaximumBlockSize

Specifies the device's maximum block size.

MinimumBlockSize

Specifies the device's minimum block size.

MaximumPartitionCount

Specifies the maximum number of partitions that can be created on the device.

FeaturesLow

Specifies the low-order 32 bits of the device features flag. This member can be one or more of following values:

Value	Meaning
TAPE_DRIVE_COMPRESSION	The device supports hardware data compression.
TAPE_DRIVE_ECC	The device supports hardware error correction.
TAPE_DRIVE_ERASE_BOP_ONLY	The device performs the erase operation from the beginning-of-partition marker only.
TAPE_DRIVE_ERASE_LONG	The device performs a long erase operation.
TAPE_DRIVE_ERASE_IMMEDIATE	The device performs an immediate erase operation —  that is, it returns when the erase operation begins.
TAPE_DRIVE_ERASE_SHORT	The device performs a short erase operation.
TAPE_DRIVE_FIXED	The device creates fixed data partitions.
TAPE_DRIVE_FIXED_BLOCK	The device supports fixed-length block mode.
TAPE_DRIVE_INITIATOR	The device creates initiator-defined partitions.
TAPE_DRIVE_PADDING	The device supports data padding.
TAPE_DRIVE_GET_ABSOLUTE_BLK	The device provides the current device-specific block address.
TAPE_DRIVE_GET_LOGICAL_BLK	The device provides the current logical block address (and logical tape partition).
TAPE_DRIVE_REPORT_SMKS	The device supports setmark reporting.
TAPE_DRIVE_SELECT	The device creates select data partitions.
TAPE_DRIVE_SET_EOT_WT_SIZE	The device supports setting the end-of-medium warning size.
TAPE_DRIVE_TAPE_CAPACITY	The device returns the maximum capacity of the tape.
TAPE_DRIVE_TAPE_REMAINING	The device returns the remaining capacity of the tape.
TAPE_DRIVE_VARIABLE_BLOCK	The device supports variable-length block mode.
TAPE_DRIVE_WRITE_PROTECT	The device returns an error if the tape is write-enabled or write-protected.
FeaturesHigh

Contains the high-order 32 bits of the device features flag. This member can be one or more of the following values:

Value	Meaning
TAPE_DRIVE_ABS_BLK_IMMED	The device moves the tape to a device-specific block address and returns as soon as the move begins.
TAPE_DRIVE_ABSOLUTE_BLK	The device moves the tape to a device specific block address.
TAPE_DRIVE_END_OF_DATA	The device moves the tape to the end-of-data marker in a partition.
TAPE_DRIVE_FILEMARKS	The device moves the tape forward (or backward) a specified number of filemarks.
TAPE_DRIVE_LOAD_UNLOAD	The device enables and disables the device for further operations.
TAPE_DRIVE_LOAD_UNLOAD_IMMED	The device supports immediate load and unload operations.
TAPE_DRIVE_LOCK_UNLOCK	The device enables and disables the tape ejection mechanism.
TAPE_DRIVE_LOCK_UNLK_IMMED	The device supports immediate lock and unlock operations.
TAPE_DRIVE_LOG_BLK_IMMED	The device moves the tape to a logical block address in a partition and returns as soon as the move begins.
TAPE_DRIVE_LOGICAL_BLK	The device moves the tape to a logical block address in a partition.
TAPE_DRIVE_RELATIVE_BLKS	The device moves the tape forward (or backward) a specified number of blocks.
TAPE_DRIVE_REVERSE_POSITION	The device moves the tape backward over blocks, filemarks, or setmarks.
TAPE_DRIVE_REWIND_IMMEDIATE	The device supports immediate rewind operation.
TAPE_DRIVE_SEQUENTIAL_FMKS	The device moves the tape forward (or backward) to the first occurrence of a specified number of consecutive filemarks.
TAPE_DRIVE_SEQUENTIAL_SMKS	The device moves the tape forward (or backward) to the first occurrence of a specified number of consecutive setmarks.
TAPE_DRIVE_SET_BLOCK_SIZE	The device supports setting the size of a fixed-length logical block or setting the variable-length block mode.
TAPE_DRIVE_SET_COMPRESSION	The device enables and disables hardware data compression.
TAPE_DRIVE_SET_ECC	The device enables and disables hardware error correction.
TAPE_DRIVE_SET_PADDING	The device enables and disables data padding.
TAPE_DRIVE_SET_REPORT_SMKS	The device enables and disables the reporting of setmarks.
TAPE_DRIVE_SETMARKS	The device moves the tape forward (or reverse) a specified number of setmarks.
TAPE_DRIVE_SPACE_IMMEDIATE	The device supports immediate spacing.
TAPE_DRIVE_TENSION	The device supports tape tensioning.
TAPE_DRIVE_TENSION_IMMED	The device supports immediate tape tensioning.
TAPE_DRIVE_WRITE_FILEMARKS	The device writes filemarks.
TAPE_DRIVE_WRITE_LONG_FMKS	The device writes long filemarks.
TAPE_DRIVE_WRITE_MARK_IMMED	The device supports immediate writing of short and long filemarks.
TAPE_DRIVE_WRITE_SETMARKS	The device writes setmarks.
TAPE_DRIVE_WRITE_SHORT_FMKS	The device writes short filemarks.
EOTWarningZoneSize

Indicates the number of bytes between the end-of-tape warning and the physical end of the tape.


TAPE_GET_MEDIA_PARAMETERS

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.

Members

Capacity

Specifies the total number of bytes on the current tape partition.

Remaining

Specifies the number of bytes between the current position and the end of the current tape partition.

BlockSize

Specifies the number of bytes per block.

PartitionCount

Specifies the number of partitions on the tape.

WriteProtected

Specifies whether the tape is write-protected. If this member is TRUE, the tape is write-protected.

Remarks

The GetTapeParameters function fills the Remaining and Capacity members with estimates of the tape remaining in the current tape partition and the total capacity of the current tape partition.

See Also

GetTapeParameters


TAPE_GET_POSITION

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.

Members

Type

Specifies the type of position. This member must be one of the following values:

Value	Description
TAPE_ABSOLUTE_POSITION	The position specified by the OffsetLow and OffsetHigh members is an absolute number of blocks from the beginning of the partition specified by the Partition member.
TAPE_LOGICAL_POSITION	The position specified by OffsetLow and OffsetHigh is relative to the current position in the partition specified by Partition.
Partition

Specifies the partition to position within. If this member is zero, the current partition is assumed.

OffsetLow

Specifies the low-order 32 bits of the block address.

OffsetHigh

Specifies the high-order 32 bits of the block address. If the high-order 32 bits are not required, this member should be zero.


TAPE_PREPARE

typedef struct _TAPE_PREPARE { // tp

    ULONG Operation;

} TAPE_PREPARE;

The TAPE_PREPARE structure describes how to prepare the tape.

Members

Operation

Specifies how to prepare the tape. This member must be one of the following values:

Value	Description
TAPE_LOCK	Locks the tape ejection mechanism so that the tape is not ejected accidentally during a tape operation.
TAPE_TENSION	Moves to the end of the tape and rewinds to the beginning of the tape. This value is ignored if the tape device does not support tensioning.
TAPE_UNLOAD	Rewinds and unloads the tape.
TAPE_UNLOCK	Unlocks the tape ejection mechanism.


TAPE_SET_DRIVE_PARAMETERS

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.

Members

ECC

Specifies whether the device supports hardware error correction. This member is TRUE if hardware error correction is supported.

Compression

Specifies whether hardware data compression is enabled or disabled. This member is TRUE if hardware data compression is enabled.

DataPadding

Specifies whether data padding is enabled or disabled. Data padding keeps the tape streaming at a constant speed. This member is TRUE if data padding is enabled.

ReportSetmarks

Specifies whether setmark reporting is enabled or disabled. This member is TRUE if setmarks are enabled.

EOTWarningZoneSize

Specifies the number of bytes between the end-of-tape warning and the physical end of the tape.


TAPE_SET_MEDIA_PARAMETERS

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.

Members

BlockSize

Specifies the number of bytes per block. Maximum and minimum block sizes can be obtained by calling the GetTapeParameters function.

Remarks

There is no longer a requirement that block sizes be powers of 2.

See Also

GetTapeParameters, SetTapeParameters


TAPE_SET_POSITION

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.

Members

Method

Specifies the type of positioning. This member must be one of the following values:

Value	Description
TAPE_ABSOLUTE_BLOCK	Moves the tape to the device-specific block address specified by the OffsetLow and OffsetHigh members. The Partition member is ignored.
TAPE_LOGICAL_BLOCK	Moves the tape to the block address specified by OffsetLow and OffsetHigh in the partition specified by Partition.
TAPE_REWIND	Moves the tape to the beginning of the current partition. The Partition, OffsetLow, and OffsetHigh members are ignored.
TAPE_SPACE_END_OF_DATA	Moves the tape to the end of the data on the partition specified by Partition.
TAPE_SPACE_FILEMARKS	Moves the tape forward (or backward) the number of filemarks specified by OffsetLow and OffsetHigh in the current partition. The Partition member is ignored.
TAPE_SPACE_RELATIVE_BLOCKS	Moves the tape forward (or backward) the number of blocks specified by OffsetLow and OffsetHigh in the current partition. The Partition member is ignored.
TAPE_SPACE_SEQUENTIAL_FMKS	Moves the tape forward (or backward) to the first occurrence of n filemarks in the current partition, where n is the number specified by OffsetLow and OffsetHigh. The Partition parameter is ignored.
TAPE_SPACE_SEQUENTIAL_SMKS	Moves the tape forward (or backward) to the first occurrence of n setmarks in the current partition, where n is the number specified by OffsetLow and OffsetHigh. The Partition member is ignored.
TAPE_SPACE_SETMARKS	Moves the tape forward (or backward) the number of setmarks specified by OffsetLow and OffsetHigh in the current partition. The Partition member is ignored.
Partition

Specifies the partition to position within. If this member is zero, the current partition is assumed.

OffsetLow

Specifies the low-order 32 bits of the block address or count for the position operation specified by the Method member.

OffsetHigh

Specifies the high-order 32 bits of the block address or count for the position operation specified by the Method member. If the high-order 32 bits are not required, this member should be zero.

Remarks

If the positioning is relative, a positive offset moves the tape forward (toward the end of the tape) and a negative offset moves the tape backward (toward the beginning of the tape).


TAPE_WRITE_MARKS

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.

Members

Type

Specifies the type of tapemark to write. This member can be one of the following values:

Value	Description
TAPE_LONG_FILEMARKS	Writes long filemarks.
TAPE_SEQUENTIAL_FILEMARKS	Writes sequential filemarks.
TAPE_SETMARKS	Writes setmarks.
TAPE_SHORT_FILEMARKS	Writes short filemarks.
Count

Specifies the number of tapemarks to write.


TBADDBITMAP  (preliminaryWindows NT)
TBADDBITMAP  (preliminary−Windows NT)

typedef struct {  // tbab

    HINSTANCE hInst;

    UINT nID;

} TBADDBITMAP, *LPTBADDBITMAP;

The TBADDBITMAP structure adds a bitmap that contains button images to a toolbar.

Members

hInst

Handle to the module instance with the executable file that contains a bitmap resource. You can add the system-defined button bitmaps to the list by specifying HINST_COMMCTRL as the hInst member and one of the following values as the nID member:

Value	Meaning
IDB_STD_LARGE_COLOR	Adds large, color standard bitmaps.
IDB_STD_SMALL_COLOR	Adds small, color standard bitmaps.
IDB_VIEW_LARGE_COLOR	Adds large, color view bitmaps.
IDB_VIEW_SMALL_COLOR	Adds small, color view bitmaps.
For more information about the system-defined standard and view bitmaps, see the following Remarks section.

nID

Resource identifier of the bitmap resource that contains the button images. If hInst is NULL, this parameter must be the handle to a bitmap that contains the button images.

Remarks

The Windows header files provide the following values that you use as indexes to the standard and view bitmaps.

STD_COPY	STD_PASTE
STD_CUT	STD_PRINT
STD_DELETE	STD_PRINTPRE
STD_FILENEW	STD_PROPERTIES
STD_FILEOPEN	STD_REDOW
STD_FILESAVE	STD_REPLACE
STD_FIND	STD_UNDO
STD_HELP
VIEW_LARGEICONS	VIEW_SORTNAME
VIEW_SMALLICONS	VIEW_SORTSIZE
VIEW_LIST	VIEW_SORTDATE
VIEW_DETAILS	VIEW_SORTTYPE
The TBADDBITMAP structure is used with the TB_ADDBITMAP message.

See Also

TB_ADDBITMAP


TBBUTTON  (preliminaryWindows NT)
TBBUTTON  (preliminary−Windows NT)

typedef struct _TBBUTTON { \\ tbb

    int iBitmap;

    int idCommand;

    BYTE fsState;

    BYTE fsStyle;

    DWORD dwData;

    int iString;

} TBBUTTON, NEAR* PTBBUTTON, FAR* LPTBBUTTON;

typedef const TBBUTTON FAR* LPCTBBUTTON;

The TBBUTTON structure contains information about a button in a toolbar.

Members

iBitmap

Zero-based index of button image.

idCommand

Command identifier associated with the button. This identifier is used in a WM_COMMAND message when the button is chosen. If the fsStyle member is the TBSTYLE_SEP value, this member must be zero.

fsState

Button state flags. This member can be a combination of the values listed in Toolbar Constants.

fsStyle

Button style. This member can be a combination of values listed in Toolbar Constants.

dwData

Application-defined value.

iString

Zero-based index of button string.

See Also

WM_COMMAND


TBNOTIFY  (preliminaryWindows NT)
TBNOTIFY  (preliminary−Windows NT)

typedef struct { \\ tbn

    NMHDR hdr;

    int iItem;

    TBBUTTON tbButton;

    int cchText;

    LPTSTR pszText;

} TBNOTIFY, FAR* LPTBNOTIFY;

The TBNOTIFY structure contains information used to process notification messages from a toolbar.

Members

hdr

Required for all WM_NOTIFY messages.

iItem

Index of the button associated with notification.

tbButton

Address of a TBBUTTON structure that contains information about the toolbar button associated with the notification.

cchText

Count of characters in the button text.

pszText

Address of the button text.

See Also

TBBUTTON, WM_NOTIFY


TBSAVEPARAMS  (preliminaryWindows NT)
TBSAVEPARAMS  (preliminary−Windows NT)

typedef struct { \\ tbsr

    HKEY hkr;

    LPCTSTR pszSubKey;

    LPCTSTR pszValueName;

} TBSAVEPARAMS;

The TBSAVEPARAMS function specifies the location in the registry where the TB_SAVERESTORE message stores and retrieves information about the state of a toolbar.

Members

hkr

Handle to the registry key.

pszSubKey

Subkey name.

pszValueName

Value name.

See Also

TB_SAVERESTORE


TC_HITTESTINFO  (preliminaryWindows NT)
TC_HITTESTINFO  (preliminary−Windows NT)

typedef struct _TC_HITTESTINFO {

    POINT pt;     // position to hit test, in client coordinates

    UINT  flags;  // variable to receive hit test results

} TC_HITTESTINFO;

The TC_HITTESTINFO structure contains information about a hit test.

Members

pt

Position to hit test, in client coordinates.

flags

Variable that receives the results of a hit test. The tab control sets this member to one of the following values:

Value	Meaning
TCHT_NOWHERE	The position is not over a tab.
TCHT_ONITEM	The position is over a tab, but not over its icon or its text. For owner-drawn tab controls, this value is specified if the position is anywhere over a tab.
TCHT_ONITEMICON	The position is over a tab's icon.
TCHT_ONITEMLABEL	The position is over a tab's text.
TCHT_ONITEM is a bitwise OR operation on TCHT_ONITEMICON and TCHT_ONITEMLABEL.

Remarks

This structure is used with the TCM_HITTEST message.

See Also

TCM_HITTEST


TC_ITEM  (preliminaryWindows NT)
TC_ITEM  (preliminary−Windows NT)

typedef struct _TC_ITEM {

    UINT mask;         // value specifying which members to retrieve or set

    UINT lpReserved1;  // reserved; do not use

    UINT lpReserved2;  // reserved; do not use

    LPSTR pszText;     // pointer to string containing tab text

    int cchTextMax;    // size of buffer pointed to by the pszText member

    int iImage;        // index to tab control's image

    LPARAM lParam;     // application-defined data associated with tab

} TC_ITEM;

The TC_ITEM structure specifies or receives the attributes of a tab.

Members

mask

Value specifying which members to retrieve or set. This member can be TCIF_ALL (meaning all members), or zero or more of the following values:

Value	Meaning
TCIF_TEXT	The pszText member is valid.
TCIF_IMAGE	The iImage member is valid.
TCIF_PARAM	The lParam member is valid.
lpReserved1

Reserved; do not use.

lpReserved2

Reserved; do not use.

pszText

Pointer to a null-terminated string that contains the tab text if the structure contains information about a tab. If the structure is receiving information, this member specifies the address of the buffer that receives the tab text.

cchTextMax

Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.

iImage

Index into the tab control's image list or  − 1 if there is no image for the tab.

lParam

Application-defined data associated with the tab. If there are more or less than 4 bytes of application-defined data per tab, an application must define a structure and use it instead of the TC_ITEM structure. The first member of the application-defined structure must be a TC_ITEMHEADER structure.

This structure is used with the TCM_INSERTITEM, TCM_GETITEM, and TCM_SETITEM messages.

See Also

TCM_GETITEM, TCM_INSERTITEM, TC_ITEMHEADER, TCM_SETITEM


TC_ITEMHEADER  (preliminaryWindows NT)
TC_ITEMHEADER  (preliminary−Windows NT)

typedef struct _TC_ITEMHEADER {

    UINT mask;         // value specifying which members to retrieve or set

    UINT lpReserved1;  // reserved; do not use

    UINT lpReserved2;  // reserved; do not use

    LPSTR pszText;     // pointer to string containing tab text

    int cchTextMax;    // size of buffer pointed to by the pszText member

    int iImage;        // index to tab control's image

} TC_ITEMHEADER;

The TC_ITEMHEADER structure specifies or receives the attributes of a tab. This structure is the same as the TC_ITEM structure, that it does not include an lParam member for application-defined data.

Members

mask

Value specifying which members to retrieve or set. This member can be TCIF_ALL (meaning all members), or zero or more of the following values:

Value	Meaning
TCIF_TEXT	The pszText member is valid.
TCIF_IMAGE	The iImage member is valid.
TCIF_PARAM	The lParam member is valid.
lpReserved1

Reserved; do not use.

lpReserved2

Reserved; do not use.

pszText

Pointer to a null-terminated string that contains the tab text if the structure contains information about a tab. If the structure is receiving information, this member specifies the address of the buffer that receives the tab text.

cchTextMax

Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.

iImage

Index into the tab control's image list or  − 1 if there is no image for the tab.

Remarks

An application cannot use the TC_ITEM structure to retrieve or set the application-defined data for tabs in a tab control with more or less than four extra bytes per tab. Instead, you should define a structure that consists of the TC_ITEMHEADER structure followed by application-defined data.

To set the number of extra bytes per tab, use the TCM_SETITEMEXTRA message.

See Also

TC_ITEM, TCM_SETITEMEXTRA


TC_KEYDOWN  (preliminaryWindows NT)
TC_KEYDOWN  (preliminary−Windows NT)

typedef struct _TC_KEYDOWN {

    NMHDR hdr;    // notification header

    WORD wVKey;   // virtual-key code

    UINT flags;
} TC_KEYDOWN;

The TC_KEYDOWN structure contains information about a key press in a tab control. This structure is used with the TCN_KEYDOWN notification message.

Members

hdr

Notification header

wVKey

Virtual key code.

flags

Same as the lParam parameter of the WM_KEYDOWN message.

See Also

TCN_KEYDOWN, WM_KEYDOWN


TEXTMETRIC

typedef struct tagTEXTMETRIC { // tm

    LONG tmHeight;

    LONG tmAscent;

    LONG tmDescent;

    LONG tmInternalLeading;

    LONG tmExternalLeading;

    LONG tmAveCharWidth;

    LONG tmMaxCharWidth;

    LONG tmWeight;

    LONG tmOverhang;

    LONG tmDigitizedAspectX;

    LONG tmDigitizedAspectY;

    BCHAR tmFirstChar;

    BCHAR tmLastChar;

    BCHAR tmDefaultChar;

    BCHAR tmBreakChar;

    BYTE tmItalic;

    BYTE tmUnderlined;

    BYTE tmStruckOut;

    BYTE tmPitchAndFamily;

    BYTE tmCharSet;

} TEXTMETRIC;

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.

Members

tmHeight

Specifies the height (ascent + descent) of characters.

tmAscent

Specifies the ascent (units above the base line) of characters.

tmDescent

Specifies the descent (units below the base line) of characters.

tmInternalLeading

Specifies the amount of leading (space) inside the bounds set by the tmHeight member. Accent marks and other diacritical characters may occur in this area. The designer may set this member to zero.

tmExternalLeading

Specifies the amount of extra leading (space) that the application adds between rows. Since this area is outside the font, it contains no marks and is not altered by text output calls in either OPAQUE or TRANSPARENT mode. The designer may set this member to zero.

tmAveCharWidth

Specifies the average width of characters in the font (generally defined as the width of the letter x). This value does not include the overhang required for bold or italic characters.

tmMaxCharWidth

Specifies the width of the widest character in the font.

tmWeight

Specifies the weight of the font.

tmOverhang

Specifies the extra width per string that may be added to some synthesized fonts. When synthesizing some attributes, such as bold or italic, graphics device interface (GDI) or a device may have to add width to a string on both a per-character and per-string basis. For example, GDI makes a string bold by expanding the spacing of each character and overstriking by an offset value; it italicizes a font by shearing the string. In either case, there is an overhang past the basic string. For bold strings, the overhang is the distance by which the overstrike is offset. For italic strings, the overhang is the amount the top of the font is sheared past the bottom of the font.

The tmOverhang member enables the application to determine how much of the character width returned by a GetTextExtentPoint32 function call on a single character is the actual character width and how much is the per-string extra width. The actual width is the extent minus the overhang.

tmDigitizedAspectX

Specifies the horizontal aspect of the device for which the font was designed.

tmDigitizedAspectY

Specifies the vertical aspect of the device for which the font was designed. The ratio of the tmDigitizedAspectX and tmDigitizedAspectY members is the aspect ratio of the device for which the font was designed.

tmFirstChar

Specifies the value of the first character defined in the font.

tmLastChar

Specifies the value of the last character defined in the font.

tmDefaultChar

Specifies the value of the character to be substituted for characters not in the font.

tmBreakChar

Specifies the value of the character that will be used to define word breaks for text justification.

tmItalic

Specifies an italic font if it is nonzero.

tmUnderlined

Specifies an underlined font if it is nonzero.

tmStruckOut

Specifies a strikeout font if it is nonzero.

tmPitchAndFamily

Specifies information about the pitch, the technology, and the family of a physical font.

The four low-order bits of this member specify information about the pitch and the technology of the font. A constant is defined for each of the four bits:

Constant	Meaning
TMPF_FIXED_PITCH	If this bit is set the font is a variable pitch font. If this bit is clear the font is a fixed pitch font. Note very carefully that those meanings are the opposite of what the constant name implies.
TMPF_VECTOR	If this bit is set the font is a vector font.
TMPF_TRUETYPE	If this bit is set the font is a TrueType font.
TMPF_DEVICE	If this bit is set the font is a device font.
An application should carefully test for qualities encoded in these low-order bits, making no arbitrary assumptions. For example, besides having their own bits set, TrueType and PostScript fonts set the TMPF_VECTOR bit. A monospace bitmap font has all of these low-order bits clear; a proportional bitmap font sets the TMPF_FIXED_PITCH bit. A Postscript printer device font sets the TMPF_DEVICE, TMPF_VECTOR, and TMPF_FIXED_PITCH bits.

The four high-order bits of tmPitchAndFamily designate the font's font family. An application can use the value 0xF0 and the bitwise AND operator to mask out the four low-order bits of tmPitchAndFamily, thus obtaining a value that can be directly compared with font family names to find an identical match. For information about font families, see the description of the LOGFONT structure.

tmCharSet

Specifies the character set of the font.

See Also

GetTextMetrics, GetTextExtentPoint32, LOGFONT


TEXTRANGE  (preliminaryWindows NT)
TEXTRANGE  (preliminary−Windows NT)

pedef struct _textrange {

    CHARRANGE chrg;

    LPSTR lpstrText;

} TEXTRANGE;

The TEXTRANGE structure receives a range of text from a rich edit control. This structure is filled in by the EM_GETTEXTRANGE message.

Members

chrg

Range of characters to get.

lpstrText

Buffer to receive the text.

See Also

EM_GETTEXTRANGE


TIME_ZONE_INFORMATION

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.

Members

Bias

Specifies the current bias, in minutes, for local time translation on this computer. The bias is the difference, in minutes, between Coordinated Universal Time (UTC) and local time. All translations between UTC and local time are based on the following formula:

UTC = local time + bias

This member is required.

StandardName

Specifies a null-terminated string associated with standard time on this operating system. For example, this parameter could contain "EST" to indicate Eastern Standard Time. This string is not used by the operating system, so anything stored there by using the SetTimeZoneInformation function is returned unchanged by the GetTimeZoneInformation function. This string can be empty.

StandardDate

Specifies a SYSTEMTIME structure that contains a date and UTC when the transition from daylight time to standard time occurs on this operating system. If this date is not specified, the wMonth member in the SYSTEMTIME structure must be zero. If this date is specified, the DaylightDate value in the TIME_ZONE_INFORMATION structure must also be specified. Local time translations done during the standard-time range are relative to the supplied StandardBias value.

This member supports two date formats. Absolute format specifies an exact date and time when standard time begins. In this form, the wYear, wMonth, wDay, wHour, wMinute, wSecond, and wMilliseconds members of the SYSTEMTIME structure are used to specify an exact date.

Day-in-month format is specified by setting the wYear member to zero, setting the wDayOfWeek member to an appropriate weekday, and using a wDay value in the range 1 through 5 to select the correct day in the month. Using this notation, the first Sunday in April can be specified, as can the last Thursday in October (5 is equal to "the last").

StandardBias

Specifies a bias value to be used during local time translations that occur during standard time. This member is ignored if a value for the StandardDate member is not supplied.

This value is added to the value of the Bias member to form the bias used during standard time. In most time zones, the value of this member is zero.

DaylightName

Specifies a null-terminated string associated with daylight time on this operating system. For example, this parameter could contain "PDT" to indicate Pacific Daylight Time. This string is not used by the operating system, so anything stored there by using the SetTimeZoneInformation function is returned unchanged by the GetTimeZoneInformation function. This string can be empty.

DaylightDate

Specifies a SYSTEMTIME structure that contains a date and UTC when the transition from standard time to daylight time occurs on this operating system. If this date is not specified, the wMonth member in the SYSTEMTIME structure must be zero. If this date is specified, the StandardDate value in the TIME_ZONE_INFORMATION structure must also be specified. Local time translations during the daylight-time range are relative to the supplied DaylightBias value. This member supports the absolute and day-in-month time formats described for the StandardDate member.

DaylightBias

Specifies a bias value to be used during local time translations that occur during daylight time. This member is ignored if a value for the DaylightDate member is not supplied.

This value is added to the value of the Bias member to form the bias used during daylight time. In most time zones, the value of this member is  − 60.

See Also

GetTimeZoneInformation, SetTimeZoneInformation, SYSTEMTIME


TOGGLEKEYS

typedef struct tagTOGGLEKEYS {     // tk

    DWORD cbSize;

    DWORD dwFlags;

} TOGGLEKEYS;

The TOGGLEKEYS structure contains information about the ToggleKeys accessibility feature. When the ToggleKeys feature is on, the computer emits a high-pitched tone whenever the user turns on the CAPS LOCK, NUM LOCK, or SCROLL LOCK key, and a low-pitched tone whenever the user turns off one of those keys.

Members

cbSize

Specifies the size, in bytes, of this structure.

dwFlags

A set of bit flags that specify properties of the ToggleKeys feature. The following bit flag values are defined:

Value	Meaning
TKF_AVAILABLE	If this flag is set, the ToggleKeys feature is available.
TKD_CONFIRMHOTKEY	Windows 95 only: A confirmation dialog box appears when the Togglekeys feature is activated by using the hot key.
TKF_HOTKEYACTIVE	If this flag is set, the user can turn the ToggleKeys feature on and off by holding down the NUM LOCK key for eight seconds.
TKF_HOTKEYSOUND	If this flag is set, the system plays a siren sound when the user turns the ToggleKeys feature on or off by using the hot key.
TKF_TOGGLEKEYSON	If this flag is set, the ToggleKeys feature is on.
Remarks

An application uses a TOGGLEKEYS structure when calling the SystemParametersInfo function with the wAction parameter set to SPI_GETTOGGLEKEYS or SPI_SETTOGGLEKEYS. When using SPI_GETTOGGLEKEYS, an application must specify the cbSize member of the TOGGLEKEYS structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SETTOGGLEKEYS value.

See Also

SystemParametersInfo


TOKEN_CONTROL

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.

Members

TokenId

Specifies a locally unique identifier (LUID) identifying this instance of the token object.

AuthenticationId

Specifies an LUID assigned to the session this token represents. There can be many tokens representing a single logon session.

ModifiedId

Specifies an LUID that changes each time the token is modified. An application can use this value as a test of whether a security context has changed since it was last used.

TokenSource

Specifies a TOKEN_SOURCE structure identifying the agency that issued the token. This information is used in audit logging.

See Also

LUID, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_DEFAULT_DACL

typedef struct _TOKEN_DEFAULT_DACL {  // tdd

    PACL DefaultDacl;

} TOKEN_DEFAULT_DACL;

The TOKEN_DEFAULT_DACL structure specifies a discretionary access-control list (ACL).

Members

DefaultDacl

Points to an ACL structure assigned by default to any objects created by the user represented by the access token.

Remarks

The GetTokenInformation function retrieves the default discretionary ACL for an access token, in the form of a TOKEN_DEFAULT_DACL structure. This structure is also used with the SetTokenInformation function to set the default discretionary ACL.

See Also

ACL, GetTokenInformation, SetTokenInformation, TOKEN_CONTROL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_GROUPS

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.

Members

GroupCount

Specifies the number of groups in the access token.

Groups

Specifies an array of SID_AND_ATTRIBUTES structures containing a token's group security identifiers (SIDs) and corresponding attributes.

The following attributes can be used with this parameter:

Value	Meaning
SE_GROUP_MANDATORY	The group cannot be disabled.
SE_GROUP_ENABLED_BY_DEFAULT	The group is enabled by default.
SE_GROUP_ENABLED	The group is enabled.
SE_GROUP_OWNER	The user is the owner of the group or the SID can be assigned as the owner of the token or objects.
SE_GROUP_LOGON_ID	The group is a logon identifier.
See Also

AdjustTokenGroups, SID_AND_ATTRIBUTES, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_OWNER

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.

Members

Owner

Points to a SID structure representing a user who will become the owner of any objects created by a process using this access token. The security identifier (SID) must be one of the user or group SIDs already in the token.

See Also

GetTokenInformation, SetTokenInformation, SID, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_PRIMARY_GROUP

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.

Members

PrimaryGroup

Points to a SID structure representing a group that will become the primary group of any objects created by a process using this access token. The security identifier (SID) must be one of the group SIDs already in the token.

See Also

GetTokenInformation, SetTokenInformation, SID, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE, TOKEN_USER


TOKEN_PRIVILEGES

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.

Members

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

typedef struct _TOKEN_SOURCE { // ts

    CHAR SourceName[8];

    LUID SourceIdentifier;

} TOKEN_SOURCE;

The TOKEN_SOURCE structure identifies the source of an access token.

Members

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

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.

Members

TokenId

Specifies a locally unique identifier (LUID) that identifies this instance of the token object.

AuthenticationId

Specifies an LUID assigned to the session this token represents. There can be many tokens representing a single logon session.

ExpirationTime

Specifies the time at which this token expires. Expiration times for access tokens are not supported in the current version of Windows NT.

TokenType

Specifies a TOKEN_TYPE enumerated type indicating whether the token is a primary or impersonation token.

ImpersonationLevel

Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type indicating the impersonation level of the token. This member is valid only if the TokenType is TokenImpersonation.

DynamicCharged

Specifies the amount, in bytes, of memory allocated for storing default protection and a primary group identifier.

DynamicAvailable

Specifies the portion of memory allocated for storing default protection and a primary group identifier not already in use. This value is returned as a count of free bytes.

GroupCount

Specifies the number of supplemental group security identifiers (SIDs) included in the token.

PrivilegeCount

Specifies the number of privileges included in the token.

ModifiedId

Specifies an LUID that changes each time the token is modified. An application can use this value as a test of whether a security context has changed since it was last used.

See Also

GetTokenInformation, LUID, SECURITY_IMPERSONATION_LEVEL, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_TYPE, TOKEN_USER


TOKEN_USER

typedef struct _TOKEN_USER { // tu

    SID_AND_ATTRIBUTES User;

} TOKEN_USER;

The TOKEN_USER structure identifies the user associated with an access token.

Members

User

Specifies an SID_AND_ATTRIBUTES structure representing the user associated with the access token. There are currently no attributes defined for user security identifiers (SIDs).

See Also

GetTokenInformation, SID_AND_ATTRIBUTES, TOKEN_CONTROL, TOKEN_DEFAULT_DACL, TOKEN_GROUPS, TOKEN_INFORMATION_CLASS, TOKEN_OWNER, TOKEN_PRIMARY_GROUP, TOKEN_PRIVILEGES, TOKEN_SOURCE, TOKEN_STATISTICS, TOKEN_TYPE


TOOLINFO  (preliminaryWindows NT)
TOOLINFO  (preliminary−Windows NT)

typedef struct {  // ti

    UINT      cbSize;

    UINT      uFlags;

    HWND      hwnd;

    UINT      uId;

    RECT      rect;

    HINSTANCE hinst;

    LPTSTR     lpszText;

} TOOLINFO, NEAR *PTOOLINFO, FAR *LPTOOLINFO;

The TOOLINFO structure contains information about a tool.

Members

cbSize

Size, in bytes, of the TOOLINFO structure. This member must be specified.

uFlags

Flag that determines how the uId member is interpreted. This member can be one of the following values:

Value	Meaning
TTF_IDISHWND	Indicates that the uId member is the window handle to the tool.
TTF_CENTERTIP	Centers the tooltip window below the tool specified by the uId member.
hwnd

Handle to the window that contains the tool. If lpszText includes the LPSTR_TEXTCALLBACK value, this member identifies the window that receives TTN_NEEDTEXT notification messages.

uId

Application-defined identifier of the tool. If uFlags includes the TTF_IDISHWND value, uId must specify the window handle to the tool.

rect

Coordinates of the bounding rectangle of the tool. The coordinates are relative to the upper-left corner of the client area of the window identified by hwnd. If uFlags includes the TTF_IDISHWND value, this member is ignored.

hinst

Handle to the instance that contains the string resource for the tool. If lpszText specifies the identifier of a string resource, this member is used.

lpszText

Pointer to the buffer that contains the text for the tool, or identifier of the string resource that contains the text. If this member is set to the LPSTR_TEXTCALLBACK value, the control sends the TTN_NEEDTEXT notification message to the owner window to retrieve the text.

Remarks

If this member is the TTF_IDISHWND value, uId is the handle of the tool. Otherwise, uId is the identifier of the tool.

See Also

TTN_NEEDTEXT


TOOLTIPTEXT  (preliminaryWindows NT)
TOOLTIPTEXT  (preliminary−Windows NT)

typedef struct { // ttt

    NMHDR     hdr;

    LPTSTR    lpszText;

    char      szText[80];

    HINSTANCE hinst;

    UINT      uFlags;

} TOOLTIPTEXT, FAR *LPTOOLTIPTEXT;

The TOOLTIPTEXT structure identifies a tool for which text is to be displayed and receives the text for the tool.

Members

hdr

Required for all WM_NOTIFY messages.

lpszText

Pointer to a string that contains or receives the text for a tool. If hinst specifies an instance handle, this member must be the identifier of a string resource.

szText

Buffer that receives the tooltip text. An application can copy the text to this buffer as an alternative to specifying a string address or string resource.

hinst

Handle to the instance that contains a string resource to be used as the tooltip text. If lpszText is the pointer to the tooltip text, this member is NULL.

uFlags

Flag that indicates how to interpret the idFrom member of the NMHDR structure that is included in the structure. If this member is the TTF_IDISHWND value, idFrom is the handle of the tool. Otherwise, idFrom is the identifier of the tool.

Remarks

This structure is used with the TTN_NEEDTEXT notification message.

See Also

NMHDR, TTN_NEEDTEXT, WM_NOTIFY


TPMPARAMS  (preliminaryWindows 95)
TPMPARAMS  [image]  (preliminary−Windows 95)

typedef struct tagTPMPARAMS {

    UINT cbSize;

    RECT rcExclude;

} TPMPARAMS, FAR *LPTPMPARAMS;

The TPMPARAMS structure contains extended parameters for the TrackPopupMenuEx function.

Members

cbsize

Size of structure, in bytes.

rcExclude

Rectangle to exclude when positioning the window, in screen coordinates.

See Also

TrackPopupMenuEx, Rectangle


TRANSMIT_FILE_BUFFERS  (preliminaryWindows NT)
TRANSMIT_FILE_BUFFERS  (preliminary−Windows NT)

typedef struct _TRANSMIT_FILE_BUFFERS {

    PVOID Head;

    DWORD HeadLength;

    PVOID Tail;

    DWORD TailLength;

} TRANSMIT_FILE_BUFFERS;

The TRANSMIT_FILE_BUFFERS structure specifies data to be transmitted before and after file data during a TransmitFile function file transfer operation.

Members

Head

Pointer to a buffer that contains data to be transmitted before the file data is transmitted.

HeadLength

Specifies the number of bytes of data in the buffer pointed to by the Head member that are to be transmitted.

Tail

Pointer to a buffer that contains data to be transmitted after the file data is transmitted.

TailLength

Specifies the number of bytes of data in the buffer pointed to by the Tail member that are to be transmitted.

See Also

TransmitFile


TTHITTESTINFO  (preliminaryWindows NT)
TTHITTESTINFO  (preliminary−Windows NT)

typedef struct _TT_HITTESTINFO { // tthti

    HWND hwnd;

    POINT pt;

    TOOLINFO ti;

} TTHITTESTINFO, FAR * LPHITTESTINFO;

The TTHITTESTINFO structure contains information that a tooltip control uses to determine whether a point is in the bounding rectangle of the specified tool. If the point is in the rectangle, the structure receives information about the tool.

Members

hwnd

Handle to the tool or window with the specified tool.

pt

Client coordinates of the point to test.

ti

Receives information about the specified tool.

Remarks

This structure is used with the TTM_HITTEST message.

See Also

TTM_HITTEST


TTPOLYCURVE

typedef struct tagTTPOLYCURVE { // ttpc

    WORD    wType;

    WORD    cpfx;

    POINTFX apfx[1];

} TTPOLYCURVE, FAR* LPTTPOLYCURVE;

The TTPOLYCURVE structure contains information about a curve in the outline of a TrueType character.

Members

wType

Specifies the type of curve described by the structure. This member can be one of the following values:

Value	Meaning
TT_PRIM_LINE	Curve is a polyline.
TT_PRIM_QSPLINE	Curve is a Bézier spline.
cpfx

Specifies the number of POINTFX structures in the array.

apfx

Specifies an array of POINTFX structures that define the polyline or Bézier spline.

Remarks

When an application calls the GetGlyphOutline function, a glyph outline for a TrueType character is returned in a TTPOLYGONHEADER structure, followed by as many TTPOLYCURVE structures as are required to describe the glyph. All points are returned as POINTFX structures and represent absolute positions, not relative moves. The starting point given by the pfxStart member of the TTPOLYGONHEADER structure is the point at which the outline for a contour begins. The TTPOLYCURVE structures that follow can be either polyline records or spline records.

Polyline records are a series of points; lines drawn between the points describe the outline of the character. Spline records represent the quadratic curves (that is, quadratic b-splines) used by TrueType.

See Also

GetGlyphOutline, POINTFX, TTPOLYGONHEADER


TTPOLYGONHEADER

typedef struct _TTPOLYGONHEADER { // ttph

    DWORD   cb;

    DWORD   dwType;

    POINTFX pfxStart;

} TTPOLYGONHEADER, FAR* LPTTPOLYGONHEADER;

The TTPOLYGONHEADER structure specifies the starting position and type of a contour in a TrueType character outline.

Members

cb

Specifies the number of bytes required by the TTPOLYGONHEADER structure and TTPOLYCURVE structure or structures required to describe the contour of the character.

dwType

Specifies the type of character outline returned. Currently, this value must be TT_POLYGON_TYPE.

pfxStart

Specifies the starting point of the contour in the character outline.

Remarks

Each TTPOLYGONHEADER structure is followed by one or more TTPOLYCURVE structures.

See Also

POINTFX, TTPOLYCURVE


TV_DISPINFO  (preliminaryWindows NT)
TV_DISPINFO  (preliminary−Windows NT)

typedef struct _TV_DISPINFO {  tvdi

    NMHDR   hdr;

    TV_ITEM item;

} TV_DISPINFO;

The TV_DISPINFO structure retrieves and sets information about a tree-view item.

Members

hdr

Required for all WM_NOTIFY messages.

item

TV_ITEM structure that identifies and contains information about the tree-view item. The mask member specifies which information is being set or retrieved; it can be one or more of the following values:

Value	Meaning
TVIF_CHILDREN	The iChildren member specifies, or is to receive, the number of child items associated with the item.
TVIF_IMAGE	The iImage member specifies, or is to receive, the index of the item's icon in the image list.
TVIF_SELECTEDIMAGE	The iSelectedImage member specifies, or is to receive, the index of the item's icon in the image list.
TVIF_TEXT	The pszText member specifies the new item text or the pointer to a buffer that is to receive the item text.
If the structure is receiving item text, you typically copy the text to the buffer pointed to by the pszText member of the TV_ITEM structure. However, you can return a string in the pszText member instead. If you do so, you cannot change or delete the string until the corresponding item text is deleted or until two additional TVN_GETDISPINFO notification messages have been sent.

Remarks

A tree-view control sends a notification message to retrieve or set an item's text if the pszText member of the item's TV_ITEM structure is the LPSTR_TEXTCALLBACK value. A tree-view control sends a notification message to retrieve or set an item's icon or small icon if the iImage or iSelectedImage member of the TV_ITEM structure is the I_IMAGECALLBACK value. A tree-view control sends a notification message to retrieve or set an item's state flags if the corresponding bits are set in the control's state callback mask.

The notification mesages are sent only if the parent window is responsible for maintaining certain information. The TV_ITEM structure is used with the TVN_GETDISPINFO and TVN_SETDISPINFO notification messages.

See Also

TV_ITEM, TVN_GETDISPINFO, TVN_SETDISPINFO


TV_HITTESTINFO  (preliminaryWindows NT)
TV_HITTESTINFO  (preliminary−Windows NT)

typedef struct _TVHITTESTINFO {  tvhtst

    POINT     pt;

    UINT      flags;

    HTREEITEM hItem;

} TV_HITTESTINFO, FAR *LPTV_HITTESTINFO;

The TV_HITTESTINFO structure contains information used to determine the location of a point relative to a tree-view control.

Members

pt

Client coordinates of point to test.

flags

Variable that receives information about the results of a hit test. This member can be one or more of the following values:

Value	Meaning
TVHT_ABOVE	Above the client area
TVHT_BELOW	Below the client area
TVHT_NOWHERE	In the client area, but below the last item
TVHT_ONITEM	On the bitmap or label associated with an item
TVHT_ONITEMBUTTON	On the button associated with an item
TVHT_ONITEMICON	On the bitmap associated with an item
TVHT_ONITEMINDENT	In the indentation associated with an item
TVHT_ONITEMLABEL	On the label (string) associated with an item
TVHT_ONITEMRIGHT	In the area to the right of an item
TVHT_ONITEMSTATEICON	On the state icon for a tree-view item that is in a user-defined state
TVHT_TOLEFT	To the right of the client area
TVHT_TORIGHT	To the left of the client area
hItem

Handle to the item that occupies the point.

Remarks

This structure is used with the TVM_HITTEST message.

See Also

TVM_HITTEST


TV_INSERTSTRUCT  (preliminaryWindows NT)
TV_INSERTSTRUCT  (preliminary−Windows NT)

typedef struct _TV_INSERTSTRUCT {  tvins

    HTREEITEM hParent;

    HTREEITEM hInsertAfter;

    TV_ITEM   item;

} TV_INSERTSTRUCT, FAR *LPTV_INSERTSTRUCT;

The TV_INSERTSTRUCT structure contains information used to add a new item to a tree-view control.

Members

hParent

Handle to the parent item. If this member is the TVI_ROOT value or NULL, the item is inserted at the root of the tree-view control.

hInsertAfter

Handle to the item after which the new item is to be inserted or one of the following values:

Value	Meaning
TVI_FIRST	Inserts the item at the beginning of the list.
TVI_LAST	Inserts the item at the end of the list.
TVI_SORT	Inserts the item into the list in alphabetical order.
item

Information about the item to add.

Remarks

This structure is used with the TVM_INSERTITEM message.

See Also

TVM_INSERTITEM


TV_ITEM  (preliminaryWindows NT)
TV_ITEM  (preliminary−Windows NT)

typedef struct _TV_ITEM {  tvi

    UINT       mask;

    HTREEITEM  hItem;

    UINT       state;

    UINT       stateMask;

    LPSTR      pszText;

    int        cchTextMax;

    int        iImage;

    int        iSelectedImage;

    int        cChildren;

    LPARAM     lParam;

} TV_ITEM, FAR *LPTV_ITEM;

The TV_ITEM structure specifies or receives attributes of a tree-view item.

Members

mask

Array of flags that indicate which of the other structure members contain valid data or which are to be filled in. This member can be a combination of the following values:

Value	Meaning
TVIF_CHILDREN	The cChildren member is valid.
TVIF_HANDLE	The hItem member is valid.
TVIF_IMAGE	The iImage member is valid.
TVIF_PARAM	The lParam member is valid.
TVIF_SELECTEDIMAGE	The iSelectedImage member is valid.
TVIF_STATE	The state and stateMask members are valid.
TVIF_TEXT	The pszText and cchTextMax members are valid.
hItem

Item to which this structure refers.

state and stateMask

Variables specifying the current state of the item and the valid states of the item. This member can be any valid combination of state values.

pszText

Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the parent window is responsible for storing the name. In this case, the tree-view control sends the parent window a TVN_GETDISPINFO notification message when it needs the item text for displaying, sorting, or editing and a TVN_SETDISPINFO notification message when the item text changes.

If the structure is receiving item attributes, this member is the pointer to the buffer that receives the item text.

cchTextMax

Size of the buffer pointed to by the pszText member if the structure is receiving item attributes. If the structure specifies item attributes, this member is ignored.

iImage and iSelectedImage

Indices of the icon image and the selected icon image within the image list. If either member is the I_IMAGECALLBACK value, the parent window is responsible for storing the corresponding images. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification message when it needs to display the images and a TVN_SETDISPINFO notification message when the images change.

cChildren

Flag indicating whether the item has associated child items. It is one if the item has one or more child items; otherwise, it is zero. If this member is the I_CHILDRENCALLBACK value, the parent window is responsible for drawing the child items. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification message when it needs to display the child items and a TVN_SETDISPINFO notification message when the attributes of a child item change.

lParam

32-bit value to associate with the item.

Remarks

This structure is used with the TVM_GETITEM, TVM_SETITEM, and TVM_INSERTITEM messages. It is also included with many of the notification messages. When the structure is used to retrieve item information, only the structure members indicated by mask contain valid data. All other members are invalid.

See Also

TVN_GETDISPINFO, TVM_GETITEM, TVM_INSERTITEM, TVN_SETDISPINFO, TVM_SETITEM


TV_KEYDOWN  (preliminaryWindows NT)
TV_KEYDOWN  (preliminary−Windows NT)

pedef struct _TV_KEYDOWN { tvkd

    NMHDR hdr;

    WORD  wVKey;

    UINT  flags;

} TV_KEYDOWN;

The TV_KEYDOWN structure contains information about a keyboard event in a tree-view control.

Members

hdr

Required for all WM_NOTIFY messages.

sVKey

Virtual key code.

flags

Always zero.

Remarks

This structure is used with the TVN_KEYDOWN notification message.

See Also

TVN_KEYDOWN


TV_SORTCB  (preliminaryWindows NT)
TV_SORTCB  (preliminary−Windows NT)

typedef struct _TV_SORTCB { tvscb

    HTREEITEM    hParent;

    PFNTVCOMPARE lpfnCompare;

    LPARAM       lParam;

} TV_SORTCB, FAR *LPTV_SORTCB;

The TV_SORTCB structure contains information used to sort child items in a tree-view control.

Members

lpfnCompare

Pointer to an application-defined callback function, which is called during a sort operation each time the relative order of two list items needs to be compared. The callback function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,

LPARAM lParamSort);

The callback function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

The lParam1 and lParam2 parameters correspond to the lParam member of the TV_ITEM structure for the two items being compared. The lParamSort parameter corresponds to the lParam member of the TV_SORTCB structure that was passed with the TVM_SORTCHILDRENCB message.

hParent

Handle to the parent item.

lParam

Application-defined 32-bit value.

Remarks

This structure is used with the TVM_SORTCHILDRENCB message.

See Also

TV_ITEM, TVM_SORTCHILDRENCB


UDACCEL  (preliminaryWindows NT)
UDACCEL  (preliminary−Windows NT)

typedef struct {

    UINT nSec;

    UINT nInc;

} UDACCEL;

The UDACCEL structure contains acceleration information for an up-down control.

Members

nSec

Amount of elapsed time, in seconds, before the position change increment specified by nInc is used.

nInc

Position change increment to use after the time specified by nSec elapses.


ULARGE_INTEGER

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.

Members

LowPart

Specifies the low-order 32 bits.

HighPart

Specifies the high-order 32 bits.

See Also

LARGE_INTEGER


UNLOAD_DLL_DEBUG_INFO

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.

Members

lpBaseOfDll

Points to the base address of the DLL in the address space of the process unloading the DLL.

See Also

DEBUG_EVENT


UNIVERSAL_NAME_INFO

typedef struct _UNIVERSAL_NAME_INFO { /* uni */

    LPTSTR  lpUniversalName;

} UNIVERSAL_NAME_INFO;

The UNIVERSAL_NAME_INFO structure contains a pointer to a Universal Naming Convention (UNC) name string.

Members

lpUniversalName

Points to a zero-terminated UNC name string.

Remarks

A universal form of a path identifies a network resource in an unambiguous, computer-independent manner. The path can then be passed to processes on other computers, allowing those processes to obtain access to the network resource.

Universal Naming Convention (UNC) names look like this:

\\servername\sharename\path\file

See Also

WNetGetUniversalName, REMOTE_NAME_INFO


USEROBJECTFLAGS  (preliminaryWindows NT)
USEROBJECTFLAGS  (preliminary−Windows NT)

typedef struct tagUSEROBJECTFLAGS {

    BOOL fInherit;

    BOOL fReserved;

    DWORD dwFlags;

} USEROBJECTFLAGS;

The USEROBJECTFLAGS structure contains information about a window station or desktop handle.

Members

fInherit

Specifies whether the handle is inherited when a new process is created. If this member is TRUE, new processes will inherit the handle.

fReserved

Reserved for future use. This member must be FALSE.

dwFlags

For window stations, this member can contain the following window station attribute flag:

Value	Description
WSF_VISIBLE	Window station has visible display surfaces.
For desktops, the dwFlags member can contain the following desktop control flag:

Value	Description
DF_ALLOWOTHERACCOUNTHOOK	Allows processes running in other accounts on the desktop to set hooks in this process.
See Also

CreateDesktop, GetUserObjectInformation, OpenDesktop, OpenInputDesktop,SetUserObjectInformation


Var

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.

Members

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.

Remarks

The Children member of the VS_VERSION_INFO structure may contain zero or more Var structures.

See Also

VarFileInfo, VS_VERSION_INFO


VarFileInfo

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.

Members

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.

Remarks

The Children member of the VS_VERSION_INFO structure may contain zero or more VarFileInfo structures.

See Also

Var, VS_VERSION_INFO


VERIFY_INFORMATION

typedef struct _VERIFY_INFORMATION {

   LARGE_INTEGER  StartingOffset;

   DWORD  Length;

} VERIFY_INFORMATION ;

The VERIFY_INFORMATION structure provides information used to logically format a disk extent.

Members

StartingOffset

Specifies the starting offset of the disk extent.

Length

Length, in bytes, of the disk extent.

Remarks

The DeviceIoControl function uses a VERIFY_INFORMATION structure as input to an IOCTL_DISK_VERIFY device I/O operation.

See Also

DeviceIoControl, IOCTL_DISK_VERIFY


VS_FIXEDFILEINFO

typedef struct _VS_FIXEDFILEINFO {  // vsffi

    DWORD dwSignature;

    DWORD dwStrucVersion;

    DWORD dwFileVersionMS;

    DWORD dwFileVersionLS;

    DWORD dwProductVersionMS;

    DWORD dwProductVersionLS;

    DWORD dwFileFlagsMask;

    DWORD dwFileFlags;

    DWORD dwFileOS;

    DWORD dwFileType;

    DWORD dwFileSubtype;

    DWORD dwFileDateMS;

    DWORD dwFileDateLS;

} VS_FIXEDFILEINFO;

The VS_FIXEDFILEINFO structure contains version information about a file. This information is language and code-page independent.

Members

dwSignature

Contains the value 0xFEEFO4BD. This is used with the szKey member of VS_VERSION_INFO data when searching a file for the VS_FIXEDFILEINFO structure.

dwStrucVersion

Specifies the binary version number of this structure. The high-order word of this member contains the major version number, and the low-order word contains the minor version number. 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.

Remarks

The Value member of the VS_VERSION_INFO data is a VS_FIXEDFILEINFO structure.

See Also

StringFileInfo, VS_VERSION_INFO


VS_VERSION_INFO

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).

Members

wLength

Specifies the length of the VS_VERSION_INFO structure. This length does not include any padding that aligns the subsequent version structure on a 32-bit boundary.

wValueLength

Specifies the length of the Value member. This value is zero if there is no Value member associated with the current version structure.

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.

Remarks

The VS_VERSION_INFO structure is the root structure that contains all other file information structures.

See Also

StringFileInfo, VarFileInfo, VS_FIXEDFILEINFO


WIN32_FIND_DATA

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.

Members

dwFileAttributes

Specifies the file attributes of the file found. This member can be one or more of the following values:

Value	Meaning
FILE_ATTRIBUTE_ARCHIVE
	The file is an archive file. Applications use this value to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED
	The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY
	The file is a directory.
FILE_ATTRIBUTE_HIDDEN
	The file is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL
	The file has no other attributes set. This value is valid only if used alone.
FILE_ATTRIBUTE_READONLY
	The file is read-only. Applications can read the file but cannot write to it or delete it.
FILE_ATTRIBUTE_SYSTEM
	The file is part of the operating system or is used exclusively by it.
FILE_ATTRIBUTE_TEMPORARY
	The file is being used for temporary storage. Applications should write to the file only if absolutely necessary. Most of the file's data remains in memory without being flushed to the media because the file will soon be deleted.
ftCreationTime

Specifies a FILETIME structure containing the time the file was created. FindFirstFile and FindNextFile report file times in Coordinated Universal Time (UTC) format. These functions set the FILETIME members to zero if the file system containing the file does not support this time member. You can use the FileTimeToLocalFileTime function to convert from UTC to local time, and then use the FileTimeToSystemTime function to convert the local time to a SYSTEMTIME structure containing individual members for the month, day, year, weekday, hour, minute, second, and millisecond.

ftLastAccessTime

Specifies a FILETIME structure containing the time that the file was last accessed. The time is in UTC format; the FILETIME members are zero if the file system does not support this time member.

ftLastWriteTime

Specifies a FILETIME structure containing the time that the file was last written to. The time is in UTC format; the FILETIME members are zero if the file system does not support this time member.

nFileSizeHigh

Specifies the high-order DWORD value of the file size, in bytes. This value is zero unless the file size is greater than MAXDWORD. The size of the file is equal to (nFileSizeHigh * MAXDWORD) + nFileSizeLow.

nFileSizeLow

Specifies the low-order DWORD value of the file size, in bytes.

dwReserved0

Reserved for future use.

dwReserved1

Reserved for future use.

cFileName

A null-terminated string that is the name of the file.

cAlternateFileName

A null-terminated string that is an alternative name for the file. This name is in the classic 8.3 (filename.ext) filename format.

Remarks

If a file has a long filename, the complete name appears in the cFileName field, and the 8.3 format truncated version of the name appears in the cAlternateFileName field.

See Also

FindFirstFile, FindNextFile, FILETIME, FileTimeToLocalFileTime, FileTimeToSystemTime


WIN32_STREAM_ID

struct WIN32_STREAM_ID {

    DWORD dwStreamId;

    DWORD dwStreamAttributes;

    LARGE_INTEGER Size;

    DWORD dwStreamNameSize;

    WCHAR  cStreamName[ ] ;

}

Members

dwStreamId

Specifies the type of data. This member can be one of the following values:

Value	Meaning
BACKUP_DATA	Standard data
BACKUP_EA_DATA	Extended attribute data
BACKUP_SECURITY_DATA	Windows NT security descriptor data
BACKUP_ALTERNATE_DATA	Alternative data streams
BACKUP_LINK	Hard link information
dwStreamAttributes

Specifies the attributes of data to facilitate cross-operating system transfer. This member must be one or more of the following values:

Value	Description
STREAM_MODIFIED_WHEN_READ	Attribute set if the stream contains data that is modified when read. Allows the backup application to know that verification of data will fail.
STREAM_CONTAINS_SECURITY	Stream contains security data (general attributes). Allows the stream to be ignored on cross-operations restore.
Size

Specifies the size, in bytes, of data. Note that this is a 64-bit value.

dwStreamNameSize

Specifies the length of the name of the alternative data stream.

cStreamName

Specifies the name of the alternative data stream, in Unicode™.

See Also

BackupRead, BackupSeek, BackupWrite


WINDOW_BUFFER_SIZE_RECORD

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.

Members

dwSize

Specifies the new size of the screen buffer, in character cell columns and rows.

Remarks

Buffer size events are placed in the input buffer when the console is in window-aware mode (ENABLE_WINDOW_INPUT).

See Also

INPUT_RECORD, ReadConsoleInput


WINDOWPLACEMENT

typedef struct _WINDOWPLACEMENT {     // 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.

Members

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_RESTORETOMAXIMIZED
	Specifies that the restored window will be maximized, regardless of whether it was maximized before it was minimized. This setting is only valid the next time the window is restored. It does not change the default restoration behavior. This flag is only valid when the SW_SHOWMINIMIZED value is specified for the showCmd member.
WPF_SETMINPOSITION
	Specifies that the coordinates of the minimized window may be specified. This flag must be specified if the coordinates are set in the ptMinPosition member.
showCmd

Specifies the current show state of the window. This member can be one of the following values:

Value	Meaning
SW_HIDE	Hides the window and activates another window.
SW_MINIMIZE	Minimizes the specified window and activates the top-level window in the system's list.
SW_RESTORE	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_SHOWNORMAL).
SW_SHOW	Activates a window and displays it in its current size and position.
SW_SHOWMAXIMIZED	Activates a window and displays it as a maximized window.
SW_SHOWMINIMIZED	Activates a window and displays it as an icon.
SW_SHOWMINNOACTIVE	Displays a window as an icon. The active window remains active.
SW_SHOWNA	Displays a window in its current state. The active window remains active.
SW_SHOWNOACTIVATE	Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL	Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position (same as SW_RESTORE).
ptMinPosition

Specifies the coordinates of the window's upper-left corner when the window is minimized.

ptMaxPosition

Specifies the coordinates of the window's upper-left corner when the window is maximized.

rcNormalPosition

Specifies the window's coordinates when the window is in the restored position.

See Also

ShowWindow, POINT, RECT


WINDOWPOS

typedef struct _WINDOWPOS { // 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.

Members

hwnd

Identifies the window.

hwndInsertAfter

Specifies the position of the window in Z order (front-to-back position). This member can be the handle of the window behind which this window is placed, or can be one of the special values listed with the SetWindowPos function.

x

Specifies the position of the left edge of the window.

y

Specifies the position of the top edge of the window.

cx

Specifies the window width, in pixels.

cy

Specifies the window height, in pixels.

flags

Specifies the window position. This member can be one of the following values:

Value	Meaning
SWP_DRAWFRAME	Draws a frame (defined in the window's class description) around the window. 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


WNDCLASS

typedef struct _WNDCLASS {    // wc

    UINT    style;

    WNDPROC lpfnWndProc;

    int     cbClsExtra;

    int     cbWndExtra;

    HANDLE  hInstance;

    HICON   hIcon;

    HCURSOR hCursor;

    HBRUSH  hbrBackground;

    LPCTSTR lpszMenuName;

    LPCTSTR lpszClassName;

} WNDCLASS;

The WNDCLASS structure contains the window class attributes that are registered by the RegisterClass function.

Members

style

Specifies the class style(s). Styles can be combined by using the bitwise OR (|) operator. This member can be any combination of the following values:

Value	Action
CS_BYTEALIGNCLIENT	Aligns the window's client area on the byte boundary (in the x direction) to enhance performance during drawing operations. This style affects the width of the window and its horizontal position on the display.
CS_BYTEALIGNWINDOW	Aligns a window on a byte boundary (in the x direction) to enhance performance during operations that involve moving or sizing the window. This style affects the width of the window and its horizontal position on the display.
CS_CLASSDC	Allocates one device context to be shared by all windows in the class. Because window classes are process specific, it is possible for multiple threads of a multithreaded application to create a window of the same class. It is also possible for the threads to attempt to use the device context simultaneously. When this happens, the operating system allows only one of the threads to successfully finish its drawing operation.
CS_DBLCLKS	Sends double-click messages to the window procedure when the user double-clicks the mouse while the cursor is within a window belonging to the class.
CS_GLOBALCLASS	Allows an application to create a window of the class regardless of the value of the hInstance parameter passed to the CreateWindow or CreateWindowEx function. If you do not specify this style, the hInstance parameter passed to the CreateWindow (or CreateWindowEx) function must be the same as the hInstance parameter passed to the RegisterClass function.
	You can create a global class by creating the window class in a dynamic-link library (DLL) and listing the name of the DLL in the registry under the following keys:
	HKEY_LOCAL_MACHINE\Software \Microsoft\Windows NT\ CurrentVersion\Windows\APPINIT_DLLS
	Whenever a process starts, the operating system loads the specified DLLs in the context of the newly started process before calling the main function in that process. The DLL must register the class during its initialization procedure and must specify the CS_GLOBALCLASS style.
CS_HREDRAW	Redraws the entire window if a movement or size adjustment changes the width of the client area.
CS_NOCLOSE	Disables the Close command on the System menu.
CS_OWNDC	Allocates a unique device context for each window in the class.
CS_PARENTDC	Specifies that child windows inherit their parent window's device context. 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 (for example, menus or dialog boxes) that are displayed briefly and then removed before other screen activity takes place. This style increases the time required to display the window, because the operating system must first allocate memory to store the bitmap.
CS_VREDRAW	Redraws the entire window if a movement or size adjustment changes the height of the client area.
lpfnWndProc

Points to the window procedure. For more information, see WindowProc.

cbClsExtra

Specifies the number of extra bytes to allocate following the window-class structure. The operating system initializes the bytes to zero.

cbWndExtra

Specifies the number of extra bytes to allocate following the window instance. The operating system initializes the bytes to zero. If an application uses the WNDCLASS structure to register a dialog box created by using the CLASS directive in the resource file, it must set this member to DLGWINDOWEXTRA.

hInstance

Identifies the instance that the window procedure of this class is within.

hIcon

Identifies the class icon. This member must be a handle of an icon resource. If this member is NULL, an application must draw an icon whenever the user minimizes the application's window.

hCursor

Identifies the class cursor. This member must be a handle of a cursor resource. If this member is NULL, an application must explicitly set the cursor shape whenever the mouse moves into the application's window.

hbrBackground

Identifies the class background brush. This member can be a handle to the physical brush to be used for painting the background, or it can be a color value. A color value must be one of the following standard system colors (the value 1 must be added to the chosen color). If a color value is given, you must convert it to one of the following HBRUSH types:

COLOR_ACTIVEBORDER
COLOR_ACTIVECAPTION
COLOR_APPWORKSPACE
COLOR_BACKGROUND
COLOR_BTNFACE
COLOR_BTNSHADOW
COLOR_BTNTEXT
COLOR_CAPTIONTEXT
COLOR_GRAYTEXT
COLOR_HIGHLIGHT
COLOR_HIGHLIGHTTEXT
COLOR_INACTIVEBORDER
COLOR_INACTIVECAPTION
COLOR_MENU
COLOR_MENUTEXT
COLOR_SCROLLBAR
COLOR_WINDOW
COLOR_WINDOWFRAME
COLOR_WINDOWTEXT

The operating system automatically deletes class background brushes when the class is freed. An application should not delete these brushes, because a class may be used by multiple instances of an application.

When this member is NULL, an application must paint its own background whenever it is requested to paint in its client area. To determine whether the background must be painted, an application can either process the WM_ERASEBKGND message or test the fErase member of the PAINTSTRUCT structure filled by the BeginPaint function.

lpszMenuName

Points to a null-terminated character string that specifies the resource name of the class menu, as the name appears in the resource file. If you use an integer to identify the menu, use the MAKEINTRESOURCE macro. If this member is NULL, windows belonging to this class have no default menu.

lpszClassName

Points to a null-terminated string or is an atom. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be in the low-order word of lpszClassName; the high-order word must be zero.

If lpszClassName is a string, it specifies the window class name.

See Also

BeginPaint, CreateWindow, CreateWindowEx, GetDC, GlobalAddAtom, MAKEINTRESOURCE, PAINTSTRUCT, RegisterClass, WindowProc, WM_PAINT


WNDCLASSEX

typedef struct _WNDCLASSEX {    // wc

    UINT    cbSize;

    UINT    style;

    WNDPROC lpfnWndProc;

    int     cbClsExtra;

    int     cbWndExtra;

    HANDLE  hInstance;

    HICON   hIcon;

    HCURSOR hCursor;

    HBRUSH  hbrBackground;

    LPCTSTR lpszMenuName;

    LPCTSTR lpszClassName;

    HICON   hIconSm;

} WNDCLASSEX;

The WNDCLASSEX structure contains window class information. It is used with the the RegisterClassEx and GetClassInfoEx functions.

The WNDCLASSEX structure is similar to the WNDCLASS structure. There are two differences. WNDCLASSEX includes the cbSize member, which specifies the size of the structure, and the hIconSm member, which contains a handle to a small icon associated with the window class.

Windows NT: The hIconSm member is not used. Set it to NULL before calling RegisterClassEx. It will be NULL when GetClassInfoEx returns.

Members

cbSize

Specifies the size, in bytes, of this structure. Set this member to sizeof(WINDOWCLASSEX). Be sure to set this member before calling the GetClassInfoEx function.

style

Specifies the class style(s). Styles can be combined by using the bitwise OR (|) operator. This member can be any combination of the following values:

Value	Action
CS_BYTEALIGNCLIENT	Aligns the window's client area on the byte boundary (in the x direction) to enhance performance during drawing operations. This style affects the width of the window and its horizontal position on the display.
CS_BYTEALIGNWINDOW	Aligns a window on a byte boundary (in the x direction) to enhance performance during operations that involve moving or sizing the window. This style affects the width of the window and its horizontal position on the display.
CS_CLASSDC	Allocates one device context to be shared by all windows in the class. Because window classes are process specific, it is possible for multiple threads of a multithreaded application to create a window of the same class. It is also possible for the threads to attempt to use the device context simultaneously. When this happens, the operating system allows only one of the threads to successfully finish its drawing operation.
CS_DBLCLKS	Sends double-click messages to the window procedure when the user double-clicks the mouse while the cursor is within a window belonging to the class.
CS_GLOBALCLASS	Allows an application to create a window of the class regardless of the value of the hInstance parameter passed to the CreateWindow or CreateWindowEx function. If you do not specify this style, the hInstance parameter passed to the CreateWindow (or CreateWindowEx) function must be the same as the hInstance parameter passed to the RegisterClass function.
	You can create a global class by creating the window class in a dynamic-link library (DLL) and listing the name of the DLL in the registry under the following keys:
	HKEY_LOCAL_MACHINE\Software \Microsoft\Windows NT\ CurrentVersion\Windows\APPINIT_DLLS
	Whenever a process starts, the operating system loads the specified DLLs in the context of the newly started process before calling the main function in that process. The DLL must register the class during its initialization procedure and must specify the CS_GLOBALCLASS style.
CS_HREDRAW	Redraws the entire window if a movement or size adjustment changes the width of the client area.
CS_NOCLOSE	Disables the Close command on the System menu.
CS_OWNDC	Allocates a unique device context for each window in the class.
CS_PARENTDC	Specifies that child windows inherit their parent window's device context. 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 (for example, menus or dialog boxes) that are displayed briefly and then removed before other screen activity takes place. This style increases the time required to display the window, because the operating system must first allocate memory to store the bitmap.
CS_VREDRAW	Redraws the entire window if a movement or size adjustment changes the height of the client area.
lpfnWndProc

Points to the window procedure. For more information, see WindowProc.

cbClsExtra

Specifies the number of extra bytes to allocate following the window-class structure. The operating system initializes the bytes to zero.

cbWndExtra

Specifies the number of extra bytes to allocate following the window instance. The operating system initializes the bytes to zero. If an application uses the WNDCLASS structure to register a dialog box created by using the CLASS directive in the resource file, it must set this member to DLGWINDOWEXTRA.

hInstance

Identifies the instance that the window procedure of this class is within.

hIcon

Identifies the class icon. This member must be a handle of an icon resource. If this member is NULL, an application must draw an icon whenever the user minimizes the application's window.

hCursor

Identifies the class cursor. This member must be a handle of a cursor resource. If this member is NULL, an application must explicitly set the cursor shape whenever the mouse moves into the application's window.

hbrBackground

Identifies the class background brush. This member can be a handle to the physical brush to be used for painting the background, or it can be a color value. A color value must be one of the following standard system colors (the value 1 must be added to the chosen color). If a color value is given, you must convert it to one of the following HBRUSH types:

COLOR_ACTIVEBORDER
COLOR_ACTIVECAPTION
COLOR_APPWORKSPACE
COLOR_BACKGROUND
COLOR_BTNFACE
COLOR_BTNSHADOW
COLOR_BTNTEXT
COLOR_CAPTIONTEXT
COLOR_GRAYTEXT
COLOR_HIGHLIGHT
COLOR_HIGHLIGHTTEXT
COLOR_INACTIVEBORDER
COLOR_INACTIVECAPTION
COLOR_MENU
COLOR_MENUTEXT
COLOR_SCROLLBAR
COLOR_WINDOW
COLOR_WINDOWFRAME
COLOR_WINDOWTEXT

The operating system automatically deletes class background brushes when the class is freed. An application should not delete these brushes, because a class may be used by multiple instances of an application.

When this member is NULL, an application must paint its own background whenever it is requested to paint in its client area. To determine whether the background must be painted, an application can either process the WM_ERASEBKGND message or test the fErase member of the PAINTSTRUCT structure filled by the BeginPaint function.

lpszMenuName

Points to a null-terminated character string that specifies the resource name of the class menu, as the name appears in the resource file. If you use an integer to identify the menu, use the MAKEINTRESOURCE macro. If this member is NULL, windows belonging to this class have no default menu.

lpszClassName

Points to a null-terminated string or is an atom. If this parameter is an atom, it must be a global atom created by a previous call to the GlobalAddAtom function. The atom, a 16-bit value, must be in the low-order word of lpszClassName; the high-order word must be zero.

If lpszClassName is a string, it specifies the window class name.

hIconSm

Windows 95: Handle to a small icon that is associated with the window class.

Windows NT: This member is not used. Set it to NULL before calling RegisterClassEx. It will be NULL when GetClassInfoEx returns.

See Also

GetClassInfoEx, RegisterClassEx, WNDCLASS


XFORM

typedef struct  _XFORM {  // 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.

Members

eM11

Specifies the following:

Operation	Meaning
Scaling	Horizontal scaling component
Rotation	Cosine of rotation angle
Reflection	Horizontal component
eM12

Specifies the following:

Operation	Meaning
Shear	Horizontal proportionality constant
Rotation	Sine of the rotation angle
eM21

Specifies the following:

Operation	Meaning
Shear	Vertical proportionality constant
Rotation	Negative sine of the rotation angle
eM22

Specifies the following:

Operation	Meaning
Scaling	Vertical scaling component
Rotation	Cosine of rotation angle
Reflection	Vertical reflection component
eDx

Specifies the horizontal translation component.

eDy

Specifies the vertical translation component.

Remarks

The following list describes how the members are used for each operation:

Operation	eM11	eM12	eM21	eM22
Rotation	Cosine	Sine	Negative sine	Cosine
Scaling	Horizontal scaling component	Nothing	Nothing	Vertical Scaling Component
Shear	Nothing	Horizontal Proportionality Constant	Vertical Proportionality Constant	Nothing
Reflection	Horizontal Reflection Component	Nothing	Nothing	Vertical Reflection Component
See Also

ExtCreateRegion, GetWorldTransform, ModifyWorldTransform, PlayEnhMetaFile, SetWorldTransform


XTYP_ADVDATA

XTYP_ADVDATA

A dynamic data exchange (DDE) client callback function receives the XTYP_ADVDATA transaction after establishing an advise loop with a server. This transaction informs the client that the value of the data item has changed.

Parameters

uFmt

Specifies the format atom of the data sent from the server.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name.

hdata

Identifies the data associated with the topic name and item name pair. This parameter is NULL if the client specified the XTYPF_NODATA flag when it requested the advise loop.

dwData1

Not used.

dwData2

Not used.

Return Value

A DDE callback function should return DDE_FACK if it processes this transaction, DDE_FBUSY if it is too busy to process this transaction, or DDE_FNOTPROCESSED if it rejects this transaction.

Remarks

An application must not free the data handle obtained during this transaction. An application must, however, copy the data associated with the data handle if the application must process the data after the callback function returns. An application can use the DdeGetData function to copy the data.

See Also

DdeClientTransaction, DdeGetData, DdePostAdvise


XTYP_ADVREQ

XTYP_ADVREQ

The system sends the XTYP_ADVREQ transaction to a server after the server calls the DdePostAdvise function. This transaction informs the server that an advise transaction is outstanding on the specified topic name and item name pair and that data corresponding to the topic name and item name pair has changed.

Parameters

uFmt

Specifies the format in which the data should be submitted to the client.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name that has changed.

hdata

Not used.

dwData1

Specifies the count, in the low-order word, of XTYP_ADVREQ transactions that remain to be processed on the same topic, item, and format name set within the context of the current call to the DdePostAdvise function. The count is zero if the current XTYP_ADVREQ transaction is the last one. A server can use this count to determine whether to create an HDATA_APPOWNED data handle for the advise data.

The low-order word is set to CADV_LATEACK if the Dynamic Data Exchange Management Library (DDEML) issued the XTYP_ADVREQ transaction because of a late-arriving DDE_ACK message from a client being outrun by the server.

The high-order word is not used.

dwData2

Not used.

Return Value

The server should first call the DdeCreateDataHandle function to create a data handle that identifies the changed data and then return the handle. The server should return NULL if it is unable to complete the transaction.

Remarks

A server cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

DdeCreateDataHandle, DdeInitialize, DdePostAdvise


XTYP_ADVSTART

XTYP_ADVSTART

A dynamic data exchange (DDE) server callback function receives the XTYP_ADVSTART transaction when a client specifies XTYP_ADVSTART as the uType parameter of the DdeClientTransaction function. A client uses this transaction to establish an advise loop with a server.

Parameters

uFmt

Specifies the data format requested by the client.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name.

hdata

Not used.

dwData1

Not used.

dwData2

Not used.

Return Value

A server callback function should return TRUE to allow an advise loop on the specified topic name and item name pair, or FALSE to deny the advise loop. If the callback function returns TRUE, any subsequent calls to the DdePostAdvise function by the server on the same topic name and item name pair causes the system to send XTYP_ADVREQ transactions to the server.

Remarks

If a client requests an advise loop on a topic name, item name, and data format for an advise loop that is already established, the Dynamic Data Exchange Management Library (DDEML) does not create a duplicate advise loop but instead alters the advise loop flags (XTYPF_ACKREQ and XTYPF_NODATA) to match the latest request.

This transaction is filtered if the server application specified the CBF_FAIL_ADVISES flag in the DdeInitialize function.

See Also

DdeClientTransaction, DdeInitialize, DdePostAdvise


XTYP_ADVSTOP

XTYP_ADVSTOP

A dynamic data exchange (DDE) server callback function receives the XTYP_ADVSTOP transaction when a client specifies XTYP_ADVSTOP in the DdeClientTransaction function. A client uses this transaction to end an advise loop with a server.

Parameters

uFmt

Specifies the data format associated with the advise loop being ended.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name.

hdata

Not used.

dwData1

Not used.

dwData2

Not used.

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_ADVISES flag in the DdeInitialize function.

See Also

DdeClientTransaction, DdeInitialize, DdePostAdvise


XTYP_CONNECT

XTYP_CONNECT

A dynamic data exchange (DDE) server callback function receives the XTYP_CONNECT transaction when a client specifies a service name that the server supports and a topic name that is not NULL in a call to the DdeConnect function.

Parameters

uFmt

Not used.

hconv

Not used.

hsz1

Identifies the topic name.

hsz2

Identifies the service name.

hdata

Not used.

dwData1

Points to a CONVCONTEXT structure that contains context information for the conversation. If the client is not a Dynamic Data Exchange Management Library (DDEML) application, this parameter is 0.

dwData2

Specifies whether the client is the same application instance as the server. If the parameter is 1, the client is the same instance. If the parameter is 0, the client is a different instance.

Return Value

A server callback function should return TRUE to allow the client to establish a conversation on the specified service name and topic name pair, or the function should return FALSE to deny the conversation. If the callback function returns TRUE and a conversation is successfully established, the system passes the conversation handle to the server by issuing an XTYP_CONNECT_CONFIRM transaction to the server's callback function (unless the server specified the CBF_SKIP_CONNECT_CONFIRMS flag in the DdeInitialize function).

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_CONNECTIONS flag in the DdeInitialize function.

A server cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

CONVCONTEXT, DdeConnect, DdeInitialize


XTYP_CONNECT_CONFIRM

XTYP_CONNECT_CONFIRM

A dynamic data exchange (DDE) server callback function receives the XTYP_CONNECT_CONFIRM transaction to confirm that a conversation has been established with a client and to provide the server with the conversation handle. The system sends this transaction as a result of a previous XTYP_CONNECT or XTYP_WILDCONNECT transaction.

Parameters

uFmt

Not used.

hconv

Identifies the new conversation.

hsz1

Identifies the topic name on which the conversation has been established.

hsz2

Identifies the service name on which the conversation has been established.

hdata

Not used.

dwData1

Not used.

dwData2

Specifies whether the client is the same application instance as the server. If the parameter is 1, the client is the same instance. If the parameter is 0, the client is a different instance.

Remarks

This transaction is filtered if the server application specified the CBF_SKIP_CONNECT_CONFIRMS flag in the DdeInitialize function.

A server cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

DdeConnect, DdeConnectList, DdeInitialize


XTYP_DISCONNECT

XTYP_DISCONNECT

An application's dynamic data exchange (DDE) callback function receives the XTYP_DISCONNECT transaction when the application's partner in a conversation uses the DdeDisconnect function to terminate the conversation.

Parameters

uFmt

Not used.

hconv

Identifies that the conversation was terminated.

hsz1

Not used.

hsz2

Not used.

hdata

Not used.

dwData1

Not used.

dwData2

Specifies whether the partners in the conversation are the same application instance. If this parameter is 1, the partners are the same instance. If this parameter is 0, the partners are different instances.

Remarks

This transaction is filtered if the application specified the CBF_SKIP_DISCONNECTS flag in the DdeInitialize function.

The application can obtain the status of the terminated conversation by calling the DdeQueryConvInfo function while processing this transaction. The conversation handle becomes invalid after the callback function returns.

An application cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

DdeDisconnect, DdeInitialize, DdeQueryConvInfo


XTYP_ERROR

XTYP_ERROR

A dynamic data exchange (DDE) callback function receives the XTYP_ERROR transaction when a critical error occurs.

Parameters

uFmt

Not used.

hconv

Identifies the conversation associated with the error. This parameter is NULL if the error is not associated with a conversation.

hsz1

Not used.

hsz2

Not used.

hdata

Not used.

dwData1

Specifies the error code in the low-order word. Currently, only the following error code is supported:

Error Code	Description
DMLERR_LOW_MEMORY	Memory is low; advise, poke, or execute data may be lost, or the system may fail.
dwData2

Not used.

Remarks

An application cannot block this transaction type; the CBR_BLOCK return code is ignored. The DDEML attempts to free memory by removing noncritical resources. An application that has blocked conversations should unblock them.


XTYP_EXECUTE

XTYP_EXECUTE

A dynamic data exchange (DDE) server callback function receives the XTYP_EXECUTE transaction when a client specifies XTYP_EXECUTE in the DdeClientTransaction function. A client uses this transaction to send a command string to the server.

Parameters

uFmt

Not used.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Not used.

hdata

Identifies the command string.

dwData1

Not used.

dwData2

Not used.

Return Value

A server callback function should return DDE_FACK if it processes this transaction, DDE_FBUSY if it is too busy to process this transaction, or DDE_FNOTPROCESSED if it rejects this transaction.

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_EXECUTES flag in the DdeInitialize function.

An application must free the data handle obtained during this transaction. An application must, however, copy the command string associated with the data handle if the application must process the string after the callback function returns. An application can use the DdeGetData function to copy the data.

Because most client applications expect a server application to perform an XTYP_EXECUTE transaction synchonrously, a server should attempt to perform all processing of the XTYP_EXECUTE transaction either from within the DDE callback function or by returning the CBR_BLOCK return code. If the hdata parameter is a command that instructs the server to terminate, the server should do so after processing the XTYP_EXECUTE transaction.

See Also

DdeClientTransaction, DdeGetData, DdeInitialize


XTYP_MONITOR

XTYP_MONITOR

The dynamic data exchange (DDE) callback function of a DDE debugging application receives the XTYP_MONITOR transaction whenever a DDE event occurs in the system. To receive this transaction, an application must specify the APPCLASS_MONITOR flag when it calls the DdeInitialize function.

Parameters

uFmt

Not used.

hconv

Not used.

hsz1

Not used.

hsz2

Not used.

hdata

Identifies a DDE object that contains information about the DDE event. The application should use the DdeAccessData function to obtain a pointer to the object.

dwData1

Not used.

dwData2

Identifies the DDE event. This parameter may be one of the following values:

Value	Meaning
MF_CALLBACKS	The system sent a transaction to a DDE callback function. The DDE object contains a MONCBSTRUCT structure that provides information about the transaction.
MF_CONV	A DDE conversation was established or terminated. The DDE object contains a MONCONVSTRUCT structure that provides information about the conversation.
MF_ERRORS	A DDE error occurred. The DDE object contains a MONERRSTRUCT structure that provides information about the error.
MF_HSZ_INFO	A DDE application created, freed, or incremented the usage count of a string handle, or a string handle was freed as a result of a call to the DdeUninitialize function. The DDE object contains a MONHSZSTRUCT structure that provides information about the string handle.
MF_LINKS	A DDE application started or stopped an advise loop. The DDE object contains a MONLINKSTRUCT structure that provides information about the advise loop.
MF_POSTMSGS	The system or an application posted a DDE message. The DDE object contains a MONMSGSTRUCT structure that provides information about the message.
MF_SENDMSGS	The system or an application sent a DDE message. The DDE object contains a MONMSGSTRUCT structure that provides information about the message.
Return Value

If the callback function processes this transaction, it should return 0.

See Also

DdeAccessData, DdeInitialize, DdeUninitialize, MONCBSTRUCT, MONCONVSTRUCT, MONERRSTRUCT, MONHSZSTRUCT, MONLINKSTRUCT, MONMSGSTRUCT


XTYP_POKE

XTYP_POKE

A dynamic data exchange (DDE) server callback function receives the XTYP_POKE transaction when a client specifies XTYP_POKE in DdeClientTransaction function. A client uses this transaction to send unsolicited data to the server.

Parameters

uFmt

Specifies the format of the data sent from the server.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name.

hdata

Identifies the data that the client is sending to the server.

dwData1

Not used.

dwData2

Not used.

Return Value

A server callback function should return the DDE_FACK flag if it processes this transaction, the DDE_FBUSY flag if it is too busy to process this transaction, or the DDE_FNOTPROCESSED flag if it rejects this transaction.

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_POKES flag in the DdeInitialize function.

See Also

DdeClientTransaction, DdeInitialize


XTYP_REGISTER

XTYP_REGISTER

A dynamic data exchange (DDE) callback function receives the XTYP_REGISTER transaction type whenever a Dynamic Data Exchange Library (DDEML) server application uses the DdeNameService function to register a service name, or whenever a non-DDEML application that supports the System topic is started.

Parameters

uFmt

Not used.

hconv

Not used.

hsz1

Identifies the base service name being registered.

hsz2

Identifies the instance-specific service name being registered.

hdata

Not used.

dwData1

Not used.

dwData2

Not used.

Remarks

This transaction is filtered if the application specified the CBF_SKIP_REGISTRATIONS flag in the DdeInitialize function.

A application cannot block this transaction type; the CBR_BLOCK return code is ignored.

An application should use the hsz1 parameter to add the service name to the list of servers available to the user. An application should use the hsz2 parameter to identify which application instance has started.

See Also

DdeInitialize, DdeNameService


XTYP_REQUEST

XTYP_REQUEST

A dynamic data exchange (DDE) server callback function receives the XTYP_REQUEST transaction when a client specifies XTYP_REQUEST in the DdeClientTransaction function. A client uses this transaction to request data from a server.

Parameters

uFmt

Specifies the format in which the server should submit data to the client.

hconv

Identifies the conversation.

hsz1

Identifies the topic name.

hsz2

Identifies the item name.

hdata

Not used.

dwData1

Not used.

dwData2

Not used.

Return Value

The server should call the DdeCreateDataHandle function to create a data handle that identifies the data and then return the handle. The server should return NULL if it is unable to complete the transaction. If the server returns NULL, the client will receive a DDE_FNOTPROCESSED flag.

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_REQUESTS flag in the DdeInitialize function.

If responding to this transaction requires lengthy processing, the server can return the CBR_BLOCK return code to suspend future transactions on the current conversation and then process the transaction asynchronously. When the server has finished and the data is ready to pass to the client, the server can call the DdeEnableCallback function to resume the conversation.

See Also

DdeClientTransaction, DdeCreateDataHandle, DdeEnableCallback, DdeInitialize


XTYP_UNREGISTER

XTYP_UNREGISTER

A dynamic data exchange (DDE) callback function receives the XTYP_UNREGISTER transaction whenever a Dynamic Data Exchange Management Library (DDEML) server application uses the DdeNameService function to unregister a service name, or whenever a non-DDEML application that supports the System topic is terminated.

Parameters

uFmt

Not used.

hconv

Not used.

hsz1

Identifies the base service name being unregistered.

hsz2

Identifies the instance-specific service name being unregistered.

hdata

Not used.

dwData1

Not used.

dwData2

Not used.

Remarks

This transaction is filtered if the application specified the CBF_SKIP_REGISTRATIONS flag in the DdeInitialize function.

A application cannot block this transaction type; the CBR_BLOCK return code is ignored.

An application should use the hsz1 parameter to remove the service name from the list of servers available to the user. An application should use the hsz2 parameter to identify which application instance has terminated.

See Also

DdeInitialize, DdeNameService


XTYP_WILDCONNECT

XTYP_WILDCONNECT

A dynamic data exchange (DDE) server callback function receives the XTYP_WILDCONNECT transaction when a client specifies a NULL service name, a NULL topic name, or both in a call to the DdeConnect or DdeConnectList function. This transaction allows a client to establish a conversation on each of the server's service name and topic name pairs that match the specified service name and topic name.

Parameters

uFmt

Not used.

hconv

Not used.

hsz1

Identifies the topic name. If this parameter is NULL, the client is requesting a conversation on all topic names that the server supports.

hsz2

Identifies the service name. If this parameter is NULL, the client is requesting a conversation on all service names that the server supports.

hdata

Not used.

dwData1

Points to a CONVCONTEXT structure that contains context information for the conversation. If the client is not a Dynamic Data Exchange Management Library (DDEML) application, this parameter is set to 0.

dwData2

Specifies whether the client is the same application instance as the server. If the parameter is 1, the client is same instance. If the parameter is 0, the client is a different instance.

Return Value

The server should return a data handle that identifies an array of HSZPAIR structures. The array should contain one structure for each service-name and topic-name pair that matches the service-name and topic-name pair requested by the client. The array must be terminated by a NULL string handle. The system sends the XTYP_CONNECT_CONFIRM transaction to the server to confirm each conversation and to pass the conversation handles to the server. The server will not receive these confirmations if it specified the CBF_SKIP_CONNECT_CONFIRMS flag in the DdeInitialize function.

The server should return NULL to refuse the XTYP_WILDCONNECT transaction.

Remarks

This transaction is filtered if the server application specified the CBF_FAIL_CONNECTIONS flag in the DdeInitialize function.

A server cannot block this transaction type; the CBR_BLOCK return code is ignored.

See Also

CONVCONTEXT, DdeConnect, DdeInitialize, HSZPAIR


XTYP_XACT_COMPLETE

XTYP_XACT_COMPLETE

A dynamic data exchange (DDE) client callback function receives the XTYP_XACT_COMPLETE transaction when an asynchronous transaction, initiated by a call to the DdeClientTransaction function, has completed.

Parameters

uFmt

Specifies the format of the data associated with the completed transaction (if applicable) or NULL if no data was exchanged during the transaction.

hconv

Identifies the conversation.

hsz1

Identifies the topic name involved in the completed transaction.

hsz2

Identifies the item name involved in the completed transaction.

hdata

Identifies the data involved in the completed transaction, if applicable. If the transaction was successful but involved no data, this parameter is TRUE. This parameter is NULL if the transaction was unsuccessful.

dwData1

Specifies the transaction identifier of the completed transaction.

dwData2

Specifies any applicable DDE_ status flags in the low word. This parameter provides support for applications dependent on DDE_APPSTATUS bits. It is recommended that applications no longer use these bits — future versions of the Dynamic Data Exchange Management Library (DDEML) may not support them.

Remarks

An application must not free the data handle obtained during this transaction. An application must, however, copy the data associated with the data handle if the application must process the data after the callback function returns. An application can use the DdeGetData function to copy the data.

See Also

DdeClientTransaction, DdeGetData