Python Programming on Win32: Appendix B - Win32 Extensions Reference


Documenting the entire Windows SDK would require a number of books this size. Therefore, we limit ourselves to a brief reference to the SDK functions and objects presented in this book.

For further information, you may wish to consult the reference guides distributed with the Python for Windows Extensions, the Microsoft SDK documentation, or any other good Windows programming text.

Common Win32 Python Objects

PyHANDLE

A PyHANDLE object represents a Win32 handle. When a PyHANDLE object is no longer referenced, the Win32 handle is automatically closed. Thus, it isn't strictly necessary (although still considered good style) to explicitly close these handles.

There are a number of variations on a PyHANDLE object, such as the PyHKEY object. These handle objects are identical in operation to a standard PyHANDLE object, but the underlying implementation uses different Win32 functions to close the handle automatically. From the Python programmers point of view, these handles all share the same interface.

Handles are obtained from a number of Win32 functions, such as functions that open or create files or registry keys. When a function requires a PyHANDLE object, it usually also accepts an integer, which is expected to be the raw Win32 handle value.

Methods

__int__()
Returns the raw Win32 handle value for this object. Thus, you can use the code int (myHandle) to obtain the Win32 handle value.

Close()
Manually closes the Win32 handle.

Detach()-
Returns the raw Win32 handle and detaches the handle from the PyHANDLE object. After making this call, the Win32 handle isn't closed automatically, and the PyHANDLE object has a Win32 handle value of zero (i.e., an invalid handle value).

Attributes

handle
The raw Win32 handle as an integer. Thus, myhandle.handle == int(myhandle).

PyIID

A PyIID object is used whenever a COM GUID is used. PyIID objects can be created using the pywintypes.IID() function, although all functions that accept a GUID also accept a string in the standard GUID format.

Methods

__str__
Obtains the string representation of a GUID. Thus, str(myiid) returns this string value.

__cmp__
Used when PyIID objects are compared. This ignores any case differences in the string representation.

Attributes

There are no attributes.

PySTARTUPINFO

A PySTARTUPINFO represents a Win32 STARTUPINFO structure. It's created by the function win32process.STARTUPINFO(). Once created, you can assign values to the attributes, then pass the object to win32process.CreateProcess().

Methods

There are no methods.

Attributes

dwFlags
A bit field that determines whether certain PySTARTUPINFO attributes are used when the process creates a window. To use many of the additional attributes, you set the appropriate mask in this attribute and also set the attributes themselves.

Any combination of the following values can be specified:

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

win32process.STARTF_FORCEOFFFEEDBACK
Indicates that the feedback cursor is forced off while the process is starting. The normal cursor is displayed.

win32process.STARTF_RUNFULLSCREEN
Indicates that the process should be run in full-screen mode, rather than in windowed mode. This flag is valid only for console applications running on an x86 computer.

win32process.STARTF_USECOUNTCHARS
If not specified, the dwXCountChars and dwYCountChars attributes are ignored.

win32process.STARTF_USEFILLATTRIBUTE
If not specified, the dwFillAttribute attribute is ignored.

win32process.STARTF_USEPOSITION
If not specified, the dwX and dwY attributes are ignored.

win32process.STARTF_USESHOWWINDOW
If this value isn't specified, the wShowWindow attribute is ignored.

win32process.STARTF_USESIZE
If not specified, the dwXSize and dwYSize attributes are ignored.

win32process.STARTF_USESTDHANDLES
Sets the standard input, standard output, and standard error handles for the process to the handles specified in the hStdInput, hStdOutput, and hStdError attributes. The CreateProcess() function's fInherit-Handles parameter must be set to true for this to work properly.

If this value isn't specified, the hStdInput, hStdOutput, and hStdError attributes are ignored.

dwX
An integer that specifies the x offset, in pixels, of the upper-left corner of a window if a new window is created. The offset is from the upper-left corner of the screen.

dwY
An integer that specifies the y offset, in pixels, of the upper-left corner of a window if a new window is created. The offset is from the upper-left corner of the screen.

dwXSize
An integer that specifies the width, in pixels, of the window if a new window is created.

dwYSize
An integer that specifies the height, in pixels, of the window if a new window is created.

dwXCountChars
For console processes, if a new console window is created, an integer that specifies the screen buffer width in character columns. This value is ignored in a GUI process.

dwYCountChars
For console processes, if a new console window is created, an integer that specifies the screen buffer height in character rows.

dwFillAttribute
An integer that specifies the initial text and background colors if a new console window is created in a console application. These values are ignored in GUI applications

hStdInput
A PyHANDLE object that is used as the standard input handle to the process.

hStdOutput
A PyHANDLE object that is used as the standard output handle to the process.

hStdError
A PyHANDLE object that is used as the standard error handle to the process.

lpDesktop
May be None, or on Windows NT/2000, a string containing either the name of the desktop only or the name of both the desktop and window station for this process.

lpTitle
For console processes, a string that contains the title displayed in the titlebar if a new console window is created. If None, the name of the executable file is

used as the window title instead. This parameter must be None for GUI or console processes that don't create a new console window.
wShowWindow
Can be any of the SW_ constants defined in win32con. For GUI processes, this specifies the default value the first time ShowWindow() is called.

Pythoncom Module

The pythoncom module provides the low-level interface between COM and Python.

CoCreateInstance()

Creates the specified COM object and returns the requested interface.

interface = CoCreateInstance (clsid, unkOuter , clsctx , iid)

Parameters

clsid
A string or PyIID object containing the class ID for the new object.

unkOuter
Typically None, or may be a Python interface object if the object is used as part of an aggregate.

clsctx
Defines the context in which the code that manages the newly created object runs. May be a combination of the following constants:

pythoncom.CLSCTX_INPROC_SERVER
The code that creates and manages objects of this class runs in the same process as the caller of the function specifying the class context.
pythoncom.CLSCTX_INPROC_HANDLER
The code that manages objects of this class is an in-process handler. This is a DLL that runs in the client process and implements client-side structures of this class when instances of the class are accessed remotely.
pythoncom.CLSCTX_LOCAL_SERVER
The EXE code that creates and manages objects of this class is loaded in a separate process space (runs on same machine but in a different process).
pythoncom.CLSCTX_REMOTE_SERVER
A remote machine context. The LocalServer32 or LocalService code that creates and manages objects of this class is run on a different machine.
pythoncom.CLSCTX_ALL
Indicates all class contexts.
pythoncom.CLSCTX_INPROC
Indicates all in-process contexts.
pythoncom.CLSCTX_SERVER
Indicates server code, whether in-process, local, or remote.

iid
A string or PyIID object that defines the interface ID requested from the new object.

Result

The result is a Python interface object, the exact type of which is determined by the iid parameter.

Comments

This function is for advanced use only; in most cases, you create COM objects using the win32com.client.Dispatch() function.

CoInitialize()

Initializes COM for apartment model threading.

CoInitialize()

Parameters

No parameters.

Comments

Equivalent to CoInitializeEx (pythoncom.COINIT_APARTMENTTHREADED). See CoInitializeEx() for more details.

CoInitializeEx()

Initializes COM for the calling thread.

CoIntializeEx (flags)

Parameters

flags
An integer defining the initialization options. May include:

pythoncom.COINIT_APARTMENTTHREADED
Initializes the thread for apartment-threaded object concurrency.
pythoncom.COINIT_MULTITHREADED
Initializes the thread for
multithreaded object concurrency.
pythoncom.COINIT_DISABLE_OLE1DDE
Disables DDE for OLE1 support.
pythoncom.COINIT_SPEED_OVER_MEMORY
Trades memory for speed.

Comments

There's no need to call this function for the Python thread that first imports the pythoncom module. Please see Appendix D, Threads, for a detailed description of COM threading models.

CoUninitialize()

Closes the COM library on the current thread, unloads all COM DLLs loaded by the thread, and forces all COM RPC connections on the thread to close.

CoUninitialize()

Comments

As described in Appendix D, this function is currently never called by the COM framework.

CoMarshalInterThreadInterfaceInStream()

Marshals a Python COM interface object from one thread to another thread in the same process.

stream = CoMarshalInterThreadInterfaceInStream (iid, interface)

Parameters

iid
A string or PyIID object that identifies the interface to be marshaled into the new stream.

interface
A Python COM interface object or win32com.client.Dispatch() instance to be marshaled.

Result

The result is a PyIStream object; that is, a Python wrapper around a COM IStream interface. This stream is typically passed to CoGetInterface-AndReleaseStream() to obtain the marshaled object in the new thread.

Comments

When paired with CoGetInterfaceAndReleaseStream(), programs can easily and reliably marshal a COM interface object to another thread in the same process. See Appendix D for further details.

CoGetInterfaceAndReleaseStream()

Unmarshals a Python interface object from a stream and releases the stream.

interface = CoGetInterfaceAndReleaseStream(stream, iid)

Parameters

stream
A PyIstream object to which the object was previously marshaled.

iid
A string or PyIID object that defines the interface to be unmarshaled from the stream.

Result

The result is a Python COM interface object, the exact type of which is determined by the iid parameter.

Comments

When paired with CoMarsha1InterThreadInterfaceInStream(), programs can easily and reliably marshal a COM interface object to another thread in the same process. See Appendix D for further details.

Win32api Module

The win32api module contains a mixed bag of useful Win32 API functions. This module contains general-purpose routines often required by programs with fairly light Windows-specific requirements. Other Python modules provide more complete coverage of specific Win32 API sets.

ShellExecute()

Performs an operation on the specified file

ShellExecute(Hwnd, Operation, File, Parameters, InitialDirectory, bShow)

Parameters

Hwnd
A handle to the window that is to be the parent window for the new process. This is primarily used for message boxes the new application may display. It's

expressed as a Python integer, and 0 (zero) may be passed if no parent is required.

Operation
A string representing the operation to perform on the file. Typically this is open. The value it takes depends on the process being executed. For example, if you execute a Python file, supported operations are open and edit. If you execute a Microsoft Word document, supported operations include open and print.

File
The name of the file to execute. Most commonly, this is a document, but a program can also be specified.

Parameter
If the File parameter contains the name of a document file, this should be None. If a program is specified, it should be a string containing the name of the document file.

InitialDirectory
The directory in which to open the document. This directory becomes the current directory for the application

bShow
An integer specifying if the main window for the application is to be shown. This is typically 1.

WinExec()

Runs the specified application.

WinExec(CommandLine, WindowShowState)

Parameters

CommandLine
The command to execute. This string can contain simply the program name in which case the Windows path is searched, or it may contain the full path to the program. Parameters to the program can also be specified here, and these parameters should contain embedded quotation marks if necessary.

WindowShowState
An optional integer that defines how the main window for the program is created. If this parameter isn't specified, win32con.SW_SHOWNORMAL is used. Common values for this flag are listed here, but for a full list, please see the Microsoft documentation for the WinExec function.

win32con.SW_SHOWNORMAL
The window is created using its default. Typically, this means the window is created in a restored or overlapped state.
win32con.SW_SHOWMAXIMIZED
The window is created maximized.
win32con.SW_SHOWMINIMIZED
The window is created minimized.
win32con.SW_HIDE
The window is created hidden.

OpenProcess()

Retrieves a handle to an existing process

handle = OpenProcess (reqdAccess, bInherit, processId)

Parameters

reqdAccess
An integer defining the access level requested on the handle. Common values are listed here, but for a full description please see the Win32 documentation for the OpenProcess() function.

win32con.PROCESS_ALL_ACCESS
Specifies all possible access flags for the process object
win32con.PROCESS_QUERY_INFORMATION
Enables using the process handle in the GetExitCodeProcess() and GetPriqrityClass() functions to read information from the process object.
win32con.PROCESS_TERMINATE
Enables using the process handle in the TerminateProcess() function to terminate the process.

bInherit
Specifies whether the returned handle can he inherited by a new process created by the current process. If true. the handle is inheritable.

processId
An integer specifying the process identifier of the process to open.

Result

The result is a PyHANDLE object containing the handle to the process.

GetSystemMetrics()

Retrieves information, in pixels, about various display elements and system configuration settings.

result = GetSystemMetrics (metricType)

Parameter

metricType
Specifies the information to retrieve. There are over 80 valid values for this function, which can be identified by constants in the win32con module that begin with SM_, such as SM_CXSCREEN. Please see the Win32 documentation for further details.

Result

An integer with the requested system metric.

GetDomainName()

Retrieves the name of the domain to which the current computer belongs.

name = GetDomainName()

Parameters

No parameters.

Result

The result is a string with the current domain name.

GetUserName()

Retrieves the username for the current thread.

name = GetUserName()

Parameters

No parameters.

Result

The result is a string with the current username. No domain information is returned, just the username.

GetComputerName()

Retrieves the NetBIOS name of the local computer, as defined in the control panel and read at system bootup.

name = GetComputerName()

Parameters

No parameters.

Result

The result is a string with the computer name.

InitiateSystemShutdown()

Intiates a shutdown and optional restart of the specified computer.

InitiateSystemShutdown(machineName, message, timeout, bForceAppsClosed, bReboot)

Parameters

machineName
The network name of the machine to shut down or None for the current machine.

message
A string that specifies a message to be displayed in the shut-down dialog box or None for no message.

timeout
An integer that specifies the time in milliseconds to display the dialog. During this period, the shutdown can be aborted by calling AbortSystem-Shutdown(). If this value is zero, no dialog is shown, and the shutdown begins immediately.

bForceAppsClosed
An integer that specifies if applications should be forced closed. If true, users aren't given an opportunity to save their work.

bReboot
An integer that specifies if the machine should be restarted after shutdown or left in a state safe to power off the computer.

Comments

To shut down the local computer, the calling process must have the SE_SHUTDOWN_NAME privilege. To shut down a remote computer, the calling process must have the SE_REMOTE_SHUTDOWN_NAME privilege on the remote computer.

AbortSystemShutdown()

Stops the system shutdown of a specified computer.

AbortSystemShutdown(machineName)

Parameters

machineName
A string that specifies the name of the computer on which to abort the shutdown or None for the local computer.

Comments

This function can programmatically abort a system shutdown initiated by InitiateSystemShutdown() during the specified timeout interval.

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.

GetCurrentThreadId()

Returns the thread identifier for the current thread.

threadId = GetCurrentThreadId()

Result

The result is an integer containing the Win32 thread ID. Until the thread terminates, this ID uniquely identifies the thread to the system.

GetCurrentProcessId()

Returns the process identifier for the current process.

processId = GetCurrentProcessId()

Result

The result is an integer containing the Win32 process ID. Until the process terminates, this ID uniquely identifies the process to the system.

Win32event Module

The win32event module contains functions that interface to the various synchronization functions available in the Win32 SDK.

WaitForSingleObject()

Waits for either the specified object to become signaled or a timeout to occur.

result = WaitForSingleObject(handle, timeout)

Parameters

handle
A PyHANDLE object or integer that specifies the object to wait for. This may be a handle to one of the following objects:

— Change notification
— Console input
— Event
— Job
— Mutex
— Process
— Semaphore
— Thread
— Waitable timer

timeout
An integer that specifies the timeout period in milliseconds or win32event. INFINITE for no timeout.

Result

The result is an integer that may be one of the following values:

win32event.WAIT_OBJECT_0
The state of the specified object is signaled.

win32event.WAIT_TIMEOUT
The time-out interval has elapsed, and the object's state is nonsignaled.

win32event.WAIT_ABANDONED
The specified object is a mutex object that wasn't released by the thread that owned the mutex object before the owning thread terminated.

WaitForMultipleObjects()

Waits for either one or all of the specified objects to become signaled or a timeout to occur.

result = WaitForMultipleObjects(handles, bWaitAll, timeout)

Parameters

handles
A sequence (e.g., list or tuple) of PyHANDLE or integer objects. The supported handle types are the same as for the win32api.WaitForSingleObject() function.

bWaitAll
An integer indicating if the function should return when all the objects have become signaled (true) or when any one of the objects becomes signaled (false).

timeout
An integer that specifies the timeout period in milliseconds or win32event. INFINITE for no timeout.

Result

The result is an integer that may be one of the following values:

win32event.WAIT_OBJECT_0 to
win32event.WAIT_OBJECT_0+len(handles)-1
If bWaitAll is true, indicates that all of the objects have become signaled. If bWaitAll is false, indicates which of the objects has become signaled.

win32event.WAIT_TIMEOUT
The timeout interval elapsed and the object's state is nonsignaled.

win32event.WAIT_0 to
win32event.WAIT_ABANDONED_0+len(handles)-
1
If bWaitAll is true, the return value indicates that the state of all specified objects is signaled and at least one of the objects is an abandoned mutex object. If bWaitAll is false, the return value minus WAIT_ABANDONED_0 indicates the sequence index of an abandoned mutex object that satisfied the wait.

MsgWaitForMultipleObjects()

Waits for either one or all the specified objects to become signaled or a timeout to occur. The specified objects can include input event objects, which are specified using the wakeMask parameter.

result = MsgWaitForMultipleObjects(handles, bWaitAll, timeout, wakeMask)

Parameters

handles
A sequence (e.g., list or tuple) of PyHANDLE or integer objects. The supported handle types are the same as for the win32api.WaitForSingleObject() function.

bWaitAll
An integer indicating if the function should return when all the objects have become signaled (true) or when any one of the objects becomes signaled (false).

timeout
An integer that specifies the timeout period in milliseconds or win32event. INFINITE for no timeout.

wakeMask
An integer that specifies input types for which an input event object handleis added to the sequence object handles. This parameter can be any combination of the following values:

win32event.QS_ALLEVENTS
An input, WM_TIMER, WM_PAINT, WM_HOTKEY or posted message is in the queue.

win32event.QS_ALLINPUT
Any message is in the queue.

win32event.QS_ALLPOSTMESSAGE
A posted message (other than those listed here) is in the queue.

win32event.QS_HOTKEY
AWM_HOTKEY message is in the queue.

win32event.QS_INPUT
An input message is in the queue.

win32event.QS_KEY
A WM_KEYUP, WM_KEYDOWN, WM_SYSKEYUP, or WM_SYSKEYDOWN message is in the queue.

win32event.QS_MOUSE
A WM_MOUSEMOVE message or mouse-button message WM_LBUTTONUP, WM_RBUTTONDOWN, and so on) is in the queue.

win32event.QS_MOUSEMOVE
A WM_MOUSEMOVE message is in the queue.

win32event.QS_PAINT
A WM_PAINT message is in the queue.

win32event.QS_POSTMESSAGE
A posted message (other than those just listed) is in the queue.

win32event.QS_SENDMESSAGE
A message sent by another thread or application is in the queue.

win32event.QS_TIMER
A WM_TIMER message is in the queue.

Result

The result is an integer that may be one of the following values:

win32event.WAIT_OBJECT_0 to
win32event.WAIT_OBJECT_0+len(handles)-1
If bWaitAll is true, indicates that all the objects have become signaled. If bWaitAll is false, indicates which of the objects has become signaled.

WAIT_OBJECT_0 + len (handles)
New input of the type specified in the wakeMask parameter is available in the thread's input queue.

win32event.WAIT_TIMEOUT
The timeout interval elapsed, and the object's state is nonsignaled.

win32event.WAIT_ABANDONED_0 to
win32event.WAIT_ABANDONED_0+len(handles)-1
If bWaitAll is true, the return value indicates the state of all specified objects is signaled and at least one of the objects is an abandoned mutex object. If bWaitAll is false, the return value minus WAIT_ABANDONED_0 indicates the sequence index of an abandoned mutex object that satisfied the wait.

CreateEvent()

Creates or opens a named or unnamed event object.

handle = CreateEvent (securityAttributes, bManualReset, bInitialState, name)

Parameters

securityAttributes
A PySECURITYATTRIBUTES object that determines whether the returned handle can be inherited by child processes. If None, the returned handle can't be inherited.

bManualReset
An integer that specifies whether an auto or manual reset object is created. If true, you must use the ResetEvent () function to manually reset the event state to nonsignaled. If false, the system automatically resets the state after a waiting thread has been released.

bInitialState
An integer that specifies if the object is to created in the signaled state. If true, the object is created signaled; otherwise it's nonsignaled.

name
A string that specifies the name of the event object or None if an unnamed object is to be created. If this name matches an existing event object, this function requests EVENT_ALL_ACCESS on the existing object. In this case, the bManualReset and bInitialState parameters are ignored as they have already been specified when the object was initially created.

Result

The result is a PyHANDLE object referencing the requested object.

SetEvent()

Sets the state of the specified event object to signaled.

SetEvent (handle)

Parameters

handle
The handle to the object to signal.

ResetEvent()

Sets the state of the specified event object to nonsignaled.

ResetEvent(handle)

Parameters

handle
The handle to the object to reset.

Win32evtlog Module

The win32evtlog module interfaces to the Win32 SDK functions that deal with the Windows NT Event Log. This module also contains generic message resources suitable for reference in Event Log records.

CloseEventLog()

Closes a handle to the Event Log.

CloseEventLog(handle)

Parameters

handle
The handle to close, as obtained from win32evtlog.OpenEventLog().

OpenEventLog()

Opens a handle to one of the Event Logs on the specified machine.

handle = OpenEventLog(machineName, logName)

Parameters

machineName
The name of the machine to connect to or None for the current machine.

logName
The name of the Event Log to open, such as Application, System, or Security.

Result

The return value is an integer handle to the Event Log.

ReadEventLog()

Reads a number of records from an open Event Log.

records = ReadEventLog(handle, readFlags, recordOffset)

Parameters

handle
An open handle to the Event Log, obtained from win32evtlog. OpenEventLog().

readFlags
Specify how the read operation is to proceed and may be a combination of the following flags:

win32evtlog.EVENTLOG_FORWARDS_READ
The Log is read in forward chronological order.
win32evtlog.EVENTLOG_BACKWARDS_READ
The Log is read in reverse chronological order.
win32evtlog.EVENTLOG_SEEK_READ
The read operation proceeds from the record specified by the recordOffset parameter. If this flag is used, readFlags must also specify EVENTLOG_FORWARDS_READ or EVENTLOG_BACKWARDS_READ, which indicates the direction for successive read operations.
win32evtlog.EVENTLOG_SEQUENTIAL_READ
The read operation proceeds sequentially from the last call to the win32evtlog.ReadEventLog() function using this handle.

recordOffset
Specifies the log-entry record number at which the read operation should start. This parameter is ignored unless the readFlags parameter includes the EVENTLOG_SEEK_READ flag.

Result

The result is a list of PyEVENTLOGRECORD objects. The number of records returned by a single call can be determined only after the call has returned.

PyEVENTLOGRECORD Object

A PyEVENTLOGRECORD object reads records from the Event Log or writes new records to the Log.

Methods

This object has no methods.

Properties

RecordNumber
The number of the Event Log record. This number can be used to find the specific record.

TimeGenerated
A Time object indicating the time the record was generated.

TimeWritten
A Time object indicating the time the record was actually written to the Log.

EvenID
An integer eventID, as defined by the application writing the record.

EventType
An integer defining the event type, which can be one of the following:

EVENTLOG_ERROR_TYPE
EVENTLOG_WARNING_TYPE
EVENTLOG_INFORMATION_TYPE
EVENTLOG_AUDIT_SUCCESS
EVENTLOG_AUDIT_FAILURE

EventCategory
An integer event category, as defined by the application writing the record.

SourceName
The name of the application that generated the Event Log record.

ComputerName
The name of the computer that generated this message.

StringInserts
A list of string inserts for this message.

Sid
The security identifier of a user to be associated with this record.

Data
The raw binary data for the Event Log record.

Messages

The win32evtlog.pyd file contains embedded messages suitable for using to write to the Event Log. Only generic messages are provided.

Message IDEvent TypeMessage Text
1 to 9Error%1
1 to 9Information%1
1 to 9Success%1
1 to 9Warning%1

Win32file Module

The win32file module contains functions that interface to the File and other I/O-related Win32 API functions.

CreateFile()

Opens or creates a file or a number of other objects and returns a handle that can access the object.

handle = CreateFile(FileName, DesiredAccess, ShareMode, SecurityAttributes,
CreationDisposition, FlagsAndAttributes, TemplateFile)

Parameters

FileName
The name of the file, pipe, or other resource to open.

DesiredAccess
An integer determining the access this file is opened with. This allows the file to be opened with read access, write access, read-write access, or device access. The following flags are defined:

0  Specifies the file to be opened with device query access. This allows the application to query the device attributes without accessing the device.
win32file.GENERIC_READ
Specifies read access to the file. Combine with win32file.GENERIC_WRITE for read-write access.
win32file.GENERIC_WRITE
Specified write access to the file. Combine with win32file.GENERICWRITE for read-write access.

ShareMode
A set of bit flags that determines how the file is to be shared. If ShareMode is 0, the file can't be shared, and all subsequent attempts to open the file fail

until the handle is closed. This parameter can be a combination of the following values:
win32file.FILE_SHARE_DELETE
Windows NT only. Only requests to open the file for delete mode succeed.
win32file.FILE_SHARE_READ
Only requests to open the file for read mode succeed.
win32file.FILE_SHARE_WRITE
Only requests to open the file for write mode succeed.

SecurityAttributes
Determines whether the file is inherited by child processes. On Windows NT, this specifies the security descriptor for the file if the underlying filesystem supports security.

CreationDisposition
Specifies what action to take on files that already exist and what action to take on files that don't already exist. This can be one of the following values:

win32file.CREATE_NEW
A new file is to be created. An exception is thrown if the file already exists.
win32file.CREATE_ALWAYS
A new file is to be created. If an existing file exists, it's overwritten.
win32file.OPEN_EXISTING
Opens an existing file. If the file doesn't already exist, an exception is thrown.
win32file.OPEN_ALWAYS
Opens an existing file if it exists, or creates a new file if not.
win32file.TRUNCATE_EXISTING
Opens the file and truncates its length to zero. The file must have been opened with write access. If the file doesn't exist, an exception is thrown.

FlagsAndAttributes
Specifies the attributes and other flags for the file. This can be a combination of the following flags:

win32file.FILE_ATTRIBUTE_ARCHIVE
The file should be archived; that is, it has the archive attribute set.
win32file.FILE_ATTRIBUTE_ENCRYPTED
The file or directory is to be encrypted. This flag has no affect if the filesystem doesn't support encryption.
win32file.FILE_ATTRIBUTE_HIDDEN
The file is hidden and not included in a normal directory listing.
win32file.FILE_ATTRIBUTE_NORMAL
There are no special attributes on the file. This value is valid only when used alone.
win32file.FILE_ATTRIBUTE_OFFLINE
The data of the file isn't available immediately because it has been moved to temporary offline storage.
win32file.FILE_ATTRIBUTE_READONLY
The file is marked as read-only. Applications can open the file for read access but not write access.
win32file.FILE_ATTRIBUTE_SYSTEM
The file is a system file and used exclusively by the operating system.
win32file.FILE_ATTRIBUTE_TEMPORARY
The file is used for temporary storage, and the operating system attempts to keep the entire file in memory when possible to speed access. Applications should remove these files as soon as possible.
win32file.FILE_FLAG_WRITETHROUGH
The system writes all data immediately to the disk, bypassing the lazywrite capabilities of the cache.
win32file.FILE_FLAG_OVERLAPPED
All I/O on this file occurs asynchronously. When a file is opened in this mode, read and write operations may return ERROR_IO_PENDING, and the event in the OVERLAPPED object is set when the I/O operation completes. Files opened with this flag must provide an OVERLAPPED object.
win32file.FILE_FLAG_NO_BUFFERING
The system opens the file with no buffering or caching.
win32file.FILE_FLAG_RANDOM_ACCESS
Indicates the file is accessed randomly. The system uses this as a hint to optimize caching of the file.
win32file.FILE_FLAG_SEQUENTIAL_SCAN
Indicates the file is accessed sequentially. The system uses this as a hint to optimize caching of the file.
win32file.FILE_FLAG_DELETE_ON_CLOSE
The operating system deletes the file automatically when the last handle to it is closed. Subsequent attempts to open the file (except for delete) fail.
win32file.FILE_FLAG_BACKUP_SEMANTICS
Indicates the file is being opened for a backup operation. Special NT security requirements apply.
win32file.FILE_FLAG_POSIX_SEMANTICS
Changes the semantics of the file to resemble POSIX files. Used only by the POSIX subsystem; shouldn't be used by Windows applications.
win32file.FILE_FLAG_OPEN_REPARSE_POINT
Inhibits the reparse functionality of the NTFS filesystem and is beyond the scope of this book.
win32file.FILE_FLAG_OPEN_NO_RECALL
Used by remote storage systems and is beyond the scope of this book.

TemplateFile
A handle to another file used as a template for file attributes or None. Under Windows 95, this parameter must be None.

Result

A PyHANDLE object to the file.

ReadFile()

Reads data from an open file.

errCode, data = ReadFile(FileHandle, Size, Overlapped)

Parameters

FileHandle
The file handle identifying the file to read from. This handle typically is obtained from win32file.CreateFile().

Size or ReadBuffer
If Size is specified as a Python integer, it's the number of bytes to read from the file. When using overlapped I/O, a ReadBuffer should be used, indicating where the ReadFile operation should place the data.

Overlapped
An OVERLAPPED object or None if overlapped I/O isn't being performed. This parameter can be omitted, in which case None is used.

Result

errCode
Either 0, or ERROR_IO_PENDING.

Data
The data read from the file.

WriteFile()

Writes data to an open file.

errCode = WriteFile(FileHandle, Data, Overlapped)

Parameters

FileHandle
The file handle identifying the file to read from. This handle typically is obtained from win32file.CreateFile().

Data
The data to write to the file, as a Python string.

Overlapped
An OVERLAPPED object or None if overlapped I/O isn't being performed. This parameter can be omitted, in which case None is used.

Result

errCode
Either 0 or ERROR_IO_PENDING.

Win32pipe Module

The win32pipe module contains functions that interface to the pipe-related Win32 API functions.

CallNamedPipe()

Connects to a message-type pipe (and waits if an instance of the pipe isn't available), writes to and reads from the pipe, and then closes the pipe.

data = CallNamedPipe(pipeName, sendData, readSize, timeout)

Parameters

pipeName
The name of the named pipe to connect to.

sendData
The data, as a Python string, to send to the service.

readSize
The size of the buffer to allocate for the result data.

timeout
Specifies the number of milliseconds to wait for the named pipe to be available or one of the following values:

win32pipe.NMPWAIT_NOWAIT
Doesn't wait for the named pipe. If the named pipe isn't available, the function throws an exception.

win32pipe.NMPWAIT_WAIT_FOREVER
Waits indefinitely.
win32pipe.NMPWAIT_USE_DEFAULT_WAIT
Uses the default timeout specified by the pipe in the call to the win32pipe.CreateNamedPipe() function.

Result

The result is the data read from the pipe, as a Python string.

CreatePipe()

Creates an anonymous pipe and returns handles to the read and write ends of the pipe.

readHandle, writeHandle = CreatePipe(SecurityAttributes, BufferSize)

Parameters

SecurityAttributes
The security to be applied to the pipe or None for the default security.

BufferSize
An integer specifying the default buffer size for the pipe. This is simply a hint to the operating system. Zero can be passed, in which case the default buffer size is used.

Result

readHandle
A handle to the read end of the pipe. This handle can be used by the win32file.ReadFile() function.

WriteHandle
A handle to the write end of the pipe. This handle can be used by the win32file.WriteFile() function.

Win32process Module

The win32process module interfaces to the process and

thread-related Win32 API functions.

CreateProcess()

Creates a new process and its primary thread.

procHandle, threadHandle, procId, threadId = CreateHandle(ApplicationName,\
                                           CommandLine,\
                                            ProcessSecurityAttributes,\
                                            ThreadSecurityAttributes,\
                                            bInheritHandles,\
                                            CreationFlags,\
                                            Environment,\
                                            CurrentDirectory,\
                                            StartupInfo)

Parameters

ApplicationName
The name of the executable that creates the process. This can either be a full path to the executable or just the filename portion. If no path is specified, Windows searches the system path for the process. This parameter may be None, in which case the executable must be specified in the CommandLine parameter.

CommandLine
The command line that executes the program. If the ApplicationName parameter is None, this must also include the name of the executable. If ApplicationName is specified, this contains additional arguments for the executable.

ProcessSecurityAttributes
The security attributes for the new process or None if the current attributes are to be inherited. Security attributes can be created using the win32security module.

ThreadSecurityAttributes
The security attributes for the main thread in the new process or None if the current attributes are to be inherited.

bInheritHandles
A boolean flag indicating if the new process should inherit Windows handles from the creating process. If true (that is, 1), each open handle in the creating process is valid for the new process.

CreationFlags
A set of flags that allow special options to be set for the created process. The following flags are currently defined:

win32process.CREATE_DEFAULT_ERROR_MODE
Creates the new process using a default error mode. If this flag isn't set, the error mode for the creating process is used. The error mode for a pro-
cess determines how the application handles certain error conditions and can be set via win32api.SetErrorMode().
win32process.CREATE_NEW_CONSOLE
The new process is created using a new console, rather than inheriting the current console. If the creating process is a GUI process, and the process to be created is a console process, this flag has no effect.
win32process.CREATE_NEW_PROCESS_GROUP
A new process group is created for this process and all subprocesses. A process group determines Ctrl-C or Ctrl-Break handling for console application.
win32process.CREATE_SEPARATE_WOW_VDM
win32process.CREATE_SHARED_WOW_VDM
Under Windows NT when executing a 16-bit program, these flags allow you to specify the Virtual DOS machine the process executes in. The Windows SDK documentation contains more information on these flags.
win32process.CREATE_SUSPENDED
The main thread of the new process is created in a suspended state. The function win32process.ResumeThread() starts the actual execution.
win32process.DEBUG_PROCESS
win32process.DEBUG_ONLY_THIS_PROCESS
These flags are typically used by Windows debuggers. The creating process is assumed to be a debugger, and the system notifies the creator of certain debug-related events.
win32process.DETACHED_PROCESS
If the new process is a console application, the process is created without a console. This is often used to execute console programs in the background.
In addition, these flags can determine the new process's system priority. These flags include:
win32process.HIGH_PRIORITY_CLASS
Used for processes that perform time-critical operations. This should be used sparingly, as a single process at this priority could cause severe disruption to the operating system itself.
win32process.IDLE_PRIORITY_CLASS
Indicates the process need execute only while the machine is otherwise unused. Suitable for background operations that can execute slowly, but should not disrupt the normal operations of the machine.
win32process.NORMAL_PRIORITY_CLASS
Indicates a normal process with no special scheduling requirements.
win32process.REALTIME_PRIORITY_CLASS
The new process has the highest possible priority. Threads at this priority preempt the threads of all other processes, including critical operating-system threads, such as the mouse driver or filesystem cache.

Environment
The environment for the new process or None to inherit the environment of the calling process. If specified, this parameter must be a dictionary of string key/value pairs or Unicode string/value pairs.

CurrentDirectory
A string that specifies the current drive and directory for the process or None to use the current drive and directory of the calling process.

StartupInfo
A Python STARTUPINFO object that specifies information about the window for the new process. A default STARTUPINFO structure can be created by calling win32process.STARTUPINFO(), and if necessary, properties of this object can be set.

Result

procHandle
A handle to the new process.

threadHandle
A handle to the main thread in the new process.

procId
The ID of the new process.

threadId
The ID of the main thread in the new process.

TerminateProcess()

Terminates the specified process and all its threads.

TerminateProcess(processHandle, exitCode)

Parameters

processHandle
A handle to the process to be terminated. This handle must have sufficient permissions to terminate the process; otherwise an ''access denied'' Win32 exception will be thrown.

exitCode
The integer exit code for the process. This exit code is returned to any program that requests it (e.g., as the return code from the os.system() function or via the win32process.GetExitCodeProcess() function.

GetProcessAffinityMask()

Retrieves the process affinity mask for a process and the system affinity mask for the system.

processMask, systemMask = GetProcessAffinityMask(handle)

Parameters

handle
A PyHANDLE or integer that represents the handle to the process for which the affinity mask is to be retrieved.

Result

processMask
An integer representing the affinity mask for the specified process.

systemMask
An integer representing the affinity mask for the system.

Comments

A process affinity mask is a bit mask in which each bit represents the processors on which a process is allowed to run. A system affinity mask is a bit mask in which each bit represents the processors that are configured in a system.

A process affinity mask is a subset of a system affinity mask. A process is allowed to run only on the processors configured into a system.

Under the Windows 95/98 family, both result masks are always set to 1.

SetProcessAffinityMask()

Sets a processor affinity mask for the threads of a specified process.

SetProcessAffinityMask(handle, affinityMask)

Parameters

handle
A PyHANDLE or integer that represents the handle to the process for which the affinity mask is to be set.

affinityMask
An integer defining the new affinity mask for the process.

Comments

A process affinity mask is a bit mask in which each bit represents the processor on which the threads of the process are allowed to run. The value of the process affinity mask must be a proper subset of the system affinity mask values obtained by the GetProcessAffinityMask() function.

This function is supported only in the Windows 2000/NT families.

SetThreadAffinityMask()

Sets the processor affinity mask for a thread.

oldMask = SetThreadAffinityMask(handle, affinityMask)

Parameters

handle
A PyHANDLE or integer that represents the handle to the thread for which the affinity mask is to be set.

affinityMask
For Windows NT/2000, an integer defining the new affinity mask for the thread. For Windows 95/98, this must be 1.

Result

On Windows NT/2000, the result is the previous affinity mask for the process. On Windows 95/98, the result is always 1.

SetPriorityClass()

Sets the priority class for the specified process.

SetPriorityClass(handle, priorityClass)

Parameters

handle
A PyHANDLE or integer that represents the handle to the thread for which the affinity mask is to be set.

priorityClass
Specifies the priority class for the process. Specify one of the following values:

win32process.ABOVE_NORMAL_PRIORITY_CLASS
Windows 2000 only: indicates a process that has priority above NORMAL_PRIORITY_CLASS but below HIGH_PRIORITY_CLASS.
win32process.BELOW_NORMAL_PRIORITY_CLASS
Windows 2000 only: indicates a process that has priority above IDLE_PRIORITY_CLASS but below NORMAL_PRIORITY_CLASS.
win32process.HIGH_PRIORITY_CLASS
A process that performs time-critical tasks that must be executed immediately. The threads of the process preempt the threads of normal or idle
priority class processes. An example is the Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class application can use nearly all available CPU time.
win32process.IDLE_PRIORITY_CLASS
Threads run only when the system is idle. The threads of the process are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle-priority class is inherited by child processes.
win32process.NORMAL_PRIORITY_CLASS
No special scheduling needs.
win32process.REALTIME_PRIORITY_CLASS
The highest possible priority. The threads of the process preempt the threads of all other processes, including operating-system processes performing important tasks. For example, a real-time process that executes for more than a brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.

Service-Related Modules

There are a number of Python modules related to Windows NT Services.

Win32serviceutil Module

The win32serviceutil module is a higher-level interface to the Win32 Service functions. It builds on the win32service module to provide a more convenient interface to service-related functions.

ControlService()

Connects to the Service Control Manager on the specified machine, then attempts to control the service.

status = ControlService(serviceName, code, machine = None)

Parameters

serviceName
The name of the service from which to obtain the status information.

code
The control code to send to the service. See the win32service. ControlService() function for further information.

machineName = None
The name of the machine to connect to. If not specified, the current machine is used.

Result

The result is the same as for the win32service.ControlService() function.

QueryServiceStatus()

Connects to the Service Control Manager on the specified machine, then queries the service status.

status = QueryServiceStatus(serviceName, machineName = None)

Parameters

serviceName
The name of the service from which to obtain the status information.

machineName = None
The name of the machine to connect to. If not specified, the current machine is used.

Result

The result is the same as the win32service.QueryServiceStatus() function's.

StartService()

Connects to the Service Control Manager on the specified machine, then starts the service using the specified arguments.

StartService(serviceName, args = None, machineName = None)

Parameters

serviceName
The name of the service to start.

args
A sequence of strings defining the arguments for the service. May be None for no arguments.

machineName
The name of the machine on which to start the service.

StopService()

Connects to the Service Control Manager on the specified machine, then sends a SERVICE_CONTROL_STOP message to the specified service.

StopService(serviceName, machineName = None)

Parameter

serviceName
The name of the service to stop.

machineName
The name of the machine on which to stop the service.

Win32service Module

The win32service module provides an interface to the low-level Windows NT Service-related functions.

OpenSCManager()

Establishes a connection to the Service Control Manager on the specified computer and opens the specified SCM database.

handle = OpenSCManager(machineName, databaseName, desiredAccess)

Parameters

machineName
Names the target computer. If None or an empty string, the function connects to the local computer.

databaseName
Names the SCM database to open. If None, the database SERVICES_ACTIVE_DATABASE is used.

desiredAccess
Specifies the access to the SCM. Any or all of the following flags can be used. The value win32service.SC_MANAGER_CONNECT is implied.

win32service.SC_MANAGER_ALL_ACCESS
Includes STANDARD_RIGHTS_REQUIRED, plus the access types in this list.
win32service.SC_MANAGER_CONNECT
Enables connecting to the SCM.
win32service.SC_MANAGER_CREATE_SERVICE
Enables calling the win32service.CreateService() function to create a service and add it to the database.
win32service.SC_MANAGER_ENUMERATE_SERVICE
Enables calling the win32service.EnumServicesStatus() function to list the services in the database.
win32service.SC_MANAGER_LOCK
Enables calling the win32service.LockServiceDatabase() function to acquire a lock on the database.
win32service.SC_MANAGER_QUERY_LOCK_STATUS
Enables calling the win32service.QueryServiceLockStatus() function to retrieve the lock status information for the database.
The following access types can also be used.
win32con.GENERIC_READ
Combines the following access types: STANDARD_RIGHTS_READ, SC_MANAGER_ENUMERATE_SERVICE, and SC_MANAGER_QUERY_LOCK_STATUS.
win32con.GENERIC_WRITE
Combines the following access types: STANDARD_RIGHTS_WRITE and SC_MANAGER_CREATE_SERVICE.
win32con.GENERIC_EXECUTE
Combines the following access types: STANDARD_RIGHTS_EXECUTE, SC_MANAGER_CONNECT, and SC_MANAGER_LOCK.

Result

handle
A handle to the SCM. When no longer needed, it should be closed with win32service.CloseServiceHandle().

OpenService()

Opens a handle to an existing service.

handle = OpenService(scHandle, serviceName, desiredAccess)

scHandle
A handle to the Service Control Manager, as obtained from win32service. OpenSCManager().

serviceName
The name of the service to open. Service-name comparisons are case-insensitive.

desiredAccess
Specifies the access to the service. Before granting the requested access, the system checks the access token of the calling process against the service object.

win32service.SERVICE_ALL_ACCESS
Includes win32con.STANDARD_RIGHTS_REQUIRED in addition to all the access types listed here.

win32service.SERVICE_CHANGE_CONFIG
Enables calling the win32service.ChangeServiceConfig() function to change the service configuration.

win32service.SERVICE_ENUMERATE_DEPENDENTS
Enables calling the win32service.EnumDependentServices() function to enumerate all the services dependent on the service.

win32service.SERVICE_INTERROGATE
Enables calling the win32service.ControlService() function to ask the service to report its status immediately.

win32service.SERVICE_PAUSE_CONTINUE
Enables calling the win32service.ControlService() function to pause or continue the service.

win32service.SERVICE_QUERY_CONFIG
Enables calling the win32service.QueryServiceConfig() function to query the service configuration.

win32service.SERVICE_QUERY_STATUS
Enables calling the win32service.QueryServiceStatus() function to ask the SCM about the status of the service.

win32service.SERVICE_START
Enables calling the win32service.StartService() function to start the service.

win32service.SERVICE_STOP
Enables calling the win32service.ControlService() function to stop the service.

win32service.SERVICE_USER_DEFINED_CONTROL
Enables calling the win32service.ControlService() function to specify a user-defined control code.

You may also specify any of the following standard access types:

win32con.GENERIC_READ
Combines the following access types: STANDARD_RIGHTS_READ, SERVICE_QUERY_CONFIG, SERVICE_QUERY_STATUS, and SERVICE_ENUMERATE_DEPENDENTS.

win32con.GENERIC_WRITE
Combines the following access types: STANDARD_RIGHTS_WRITE and SERVICE_CHANGE_CONFIG.

win32con.GENERIC_EXECUTE
Combines the following access types: STANDARD_RIGHTS_EXECUTE, SERVICE_START, SERVICE_STOP, SERVICE_PAUSE_CONTINUE, SERVICE_INTERROGATE, and SERVICE_USER_DEFINED_CONTROL.

Result

handle
A handle to the service. This should be closed using win32service. CloseServiceHandle().

CloseServiceHandle()

Closes a handle to a service or the Service Control Manager.

CloseServiceHandle(handle)

Parameters

handle
A handle obtained from win32service.OpenSCManager(), win32service. OpenService(), or win32service.CreateService().

ControlService()

Sends control requests to a service.

status = ControlService(handle, code)

Parameters

handle
Handle to the service, as obtained from win32service.OpenService().

code
Specifies the requested control code. May be one of the following values:

win32service.SERVICE_CONTROL_STOP
Requests the service to stop. The handle must have SERVICE_STOP access.
win32service.SERVICE_CONTROL_PAUSE
Requests the service to pause. The handle must have SERVICE_PAUSE_CONTINUE access.
win32service.SERVICE_CONTROL_CONTINUE
Requests the paused service to resume. The handle must have SERVICE_PAUSE_CONTINUE access.
win32service.SERVICE_CONTROL_INTERROGATE
Requests the service to update immediately its current status information to the SCM. The handle must have SERVICE_INTERROGATE access.

Result

The result is a tuple in the same format as returned by the win32service. QueryServiceStatus() function.

QueryServiceStatus()

Queries a service for status.

status = QueryServiceStatus(handle)

Parameters

handle
Handle to the service, as obtained from win32service.OpenService().

Result

The result is a tuple with the following fields:

serviceType
A combination of the following flags:

win32service.SERVICE_WIN32_OWN_PROCESS
Indicates a service that runs in its own process.
win32service.SERVICE_WIN32_SHARE_PROCESS
Indicates a service that shares a process with other services.
win32service.SERVICE_KERNEL_DRIVER
Indicates a device driver.
win32service.SERVICE_FILE_SYSTEM_DRIVER
Indicates a filesystem driver.
win32service.SERVICE_INTERACTIVE_PROCESS
A service process that can interact with the desktop.

currentState
A combination of the following flags:

win32service.SERVICE_STOPPED
The service isn't running.
win32service.SERVICE_START_PENDING
The service is starting.
win32service.SERVICE_STOP_PENDING
The service is stopping.
win32service.SERVICE_RUNNING
The service is running.
win32service.SERVICE_CONTINUE_PENDING
The service continue is pending.
win32service.SERVICE_PAUSE_PENDING
The service pause is pending.
win32service.SERVICE_PAUSED
The service is paused.

controlsAccepted
A set of flags indicating the controls the service accepts:

win32service.SERVICE_ACCEPT_STOP
The service can be stopped. This enables the SERVICE_CONTROL_STOP value.
win32service.SERVICE_ACCEPT_PAUSE_CONTINUE
The service can be paused and continued. This enables the SERVICE_CONTROL_PAUSE and SERVICE_CONTROL_CONTINUE values.
win32service.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 win32service.ControlService() function can't send this control code.
Windows 2000 supports additional flags. See the Windows NT documentation for further information.

win32ExitCode
A Win32 error code the service may set while it's starting or stopping. If this value is win32service.ERROR_SERVICE_SPECIFIC_ERROR, the next tuple item contains the service-specific error code.

serviceSpecificExitCode
An error code set by the service. This should be ignored unless the previous item is win32service.ERROR_SERVICE_SPECIFIC_ERROR.

checkPoint
A value the service periodically increments to report its progress during lengthy start, stop, pause, or continue operations. It's used primarily to indicate to the SCM that meaningful initialization or termination is still happening.

waitHint
Specifies an estimate of the amount of time, in milliseconds, that the service expects a pending start, stop, pause, or continue operation to take before the service makes its next call to the win32service.SetServiceStatus() function with either an incremented checkPoint value or a change in currentState.

StartService()

Starts the service identified by the handle.

StartService(handle, args)

Parameters

handle
A handle to a service, as obtained from win32service.OpenService().

args
A sequence of strings (or Unicode objects) to use as arguments to the service. None may be specified if no arguments are required.

Servicemanager Module

The servicemanager module is implemented by the Python service framework; thus, there is no servicemanager file on disk, and the module is available only when code is running under the Service Control Manager. See Chapter 18, Windows NT Services, for more information.

LogMsg()

Logs a specific message to the Event Log.

LogMsg(errorType, eventId, inserts = ())

Parameters

errorType
An integer that identifies the class of error. May be either the EVENTLOG_ERROR_TYPE, EVENTLOG_WARNING_TYPE, EVENTLOG_INFORMATION_TYPE, EVENTLOG_AUDIT_SUCCESS, or EVENTLOG_AUDIT_FAILURE constants from the servicemanager module.

eventId
The event ID, which can be any of the valid IDs listed in the messages section for this module.

inserts = ()
A sequence with the inserts for the message. Each sequence item must be a string and is replaced with the specified marker in the message text.

LogInfoMsg()
LogWarningMsg()
LogErrorMsg()

Logs a generic informational, warning or error message to the Event Log.

LogInfoMsg(message)
LogWarningMsg(message)
LogErrorMsg(message)

Parameters

message
A string containing the message to be written.

Messages

The servicemanager module contains embedded messages suitable to write to the Event Log using the methods described previously.

Message IDEvent TypeMessage Text
0xFFError%1
0x1000_PYS_SERVICE_STARTINGInformationThe %1 service is starting %2.
0x1002_PYS_SERVICE_STARTEDInformationThe %1 service has started %2.
0x1003_PYS_SERVICE_STOPPINGInformationThe %1 service is stopping %2.
0x1004_PYS_SERVICE_STOPPEDInformationThe %1 service has stopped %2.
1 to 9Error%1
1 to 9Information%1
1 to 9Success%1
1 to 9Warning%1

Win32net Module

NetGroupGetInfo

Retrieves information about a particular global group in the security database.

data = NetGroupGetInfo (serverName, groupName, level)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
A string specifying the name of the global group.

level
An integer that specifies the information level of the returned data. May be 0, 1, or 2.

Result

The result is a dictionary, the contents of which are defined by one of the GROUP_INFO structures, depending on the level parameter.

NetGroupGetUsers

Enumerates the users in a global group.

entries, total, resume = NetGroupGetUsers (serverName, groupName, level, resume = 0, len=4096)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
A string specifying the name of the global group.

level
An integer that specifies the level of data to be returned for each group. Only 0(zero) is currently valid.

resume
A value that controls the iteration when there are a large number of servers to list. Zero should be passed the first time it's called, and while a non-zero resume result is returned from the function, it can be called again with the new resume value to obtain the rest of the servers.

len = 4096
A hint to the Win32 function about how much data to allocate. See the Win32 documentation for more details.

Result

The result is a tuple with the following items:

entries
A list of dictionaries of format GROUP_USERS_INFO_0, one for each user returned.

total
The total number of items left to read before making the call. Thus, totallen (entries) are the number of entries left to read after this call.

resume
A resume handle that can obtain the next set of users. When resume is zero, there are no more items to read.

NetGroupSetUsers()

Sets the membership for the specified global group. Each user you specify is enrolled as a member of the global group. Users you don't specify, but who are currently members of the global group, will have their membership revoked.

NetGroupSetUsers(serverName, groupName ,level=0 , members)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
A string  specifying the name of the global group.

level
An integer that specifies the data in the members parameter. Only 0 (zero) is currently valid.

members
A sequence (for example, list or tuple) of dictionaries, each of which contains data that corresponds to the GROUP_USERS_INFO_0 structure.

NetGroupSetInfo()

Sets information about a particular group account on a server.

NetGroupSetInfo(serverName, groupName, level, data)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
A string specifying the name of the global group.

level
An integer that specifies the data in the data parameter. May be 0, 1, 2, 1002, or 1005.

data
A dictionary with the data for the group. The data is in the format of one of the GROUP_INFO structures, depending on the level parameter.

NetGroupAdd()

Creates a new global group in the security database.

NetGroupAdd(serverName, level, data)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

level
An integer that specifies the data in the data parameter. May be 0, 1, or 2.

data
A dictionary with the data for the group. The data is in the format of one of the GROUP_INFO structures, depending on the level parameter.

NetGroupAddUser()

Gives an existing user account membership in an existing global group in the security database.

NetGroupAddUser(serverName, groupName, userName)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
A string specifying the name of the global group to which the user is to be given membership.

userName
A string specifying the name of the user to be added to the group.

NetGroupDel()

Deletes a global group from the security database.

NetGroupDel(serverName, groupName)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
A string specifying the name of the global group to be deleted.

NetGroupDelUser()

Deletes a user from the specified global group

NetGroupDelUser(serverName, groupName, userName)

Parameters

serverName
A string-specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
A string specifying the name of the global group from which the user is to be removed.

userName
A string specifying the name of the user to be removed from to the group.

NetGroupEnum

Retrieves information about each global group in the security database.

entries, total, resume = NetGroupEnum(serverName, level, resume = 0, len=4096

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

level
An integer that specifies the level of the data to be returned. May be 0, 1, or 2.

resume
A value that controls the iteration when there are a large number of servers to list. Zero should be passed the first time it's called, and while a non-zero resume result is returned from the function, it can be called again with the new resume value to obtain the rest of the servers.

len = 4096
A hint to the Win32 function about how much data to allocate. See the Win32 documentation for more details.

Result

The result is a tuple with the following items:

entries
A list of dictionaries in the format of one of the GROUP_INFO structures, depending on the level parameter, one for each group returned.

total
The total number of items left to read before making the call. Thus, totallen (entries) are the number of entries left to read after this call.

resume
A resume handle that can obtain the next set of users. When resume is zero, there are no more items to read.

NetLocalGroupAddMembers()

Adds users to a local group.

NetLocalGroupAddMembers(serverName, groupName, level, members)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
A string specifying the name of the global group.

level
An integer that specifies the data in the members parameter; can be 0 or 3.

members
A sequence (for example, list or tuple) of dictionaries, each of which contains data that corresponds to the relevant LOCALGROUP_MEMBERS_INFO structure, depending on the level parameter.

NetLocalGroupDelMembers()

Deletes one or more users from a local group.

NetLocalGroupDelMembers(serverName, groupName, level, members)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
A string specifying the name of the global group.

level
An integer that specifies the data in the members parameter; can be 0 or 3.

members
A sequence (for example, list or tuple) of dictionaries, each of which contains data that corresponds to the relevant LOCALGROUP_MEMBERS_INFO structure, depending on the level parameter.

NetLocalGroupGetMembers

Enumerates the members in a local group.

entries, total, resume = NetLocalGroupGetMembers(serverName, groupName, level, resume = 0, len=4096)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
The name of the local group from which to enumerate the members.

level
An integer that specifies the level of data to be returned. May be 0, 1, 2, or 3.

resume
A value that controls the iteration when there are many servers to list. Zero should be passed the first time it's called, and while a non-zero resume result is returned from the function, it can be called again with the new resume value to obtain the rest of the servers.

len = 4096
A hint to the Win32 function about how much data to allocate. See the Win32 documentation for more details.

Result

The result is a tuple with the following items:

entries
A list of dictionaries in the format of one of the LOCALGROUP_MEMBERS_INFO structures; depending on the level parameter, one for each user returned.

total
The total number of items left to read before making the call. Thus, totallen(entries) are the number of entries left to read after this call.

resume
A resume handle that can obtain the next set of users. When resume is zero, there are no more items to read.

NetLocalGroupSetMembers()

Sets the members of a local group. Any existing members not listed are removed.

NetLocalGroupSetMembers(serverName, groupName, level, members)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

groupName
A string specifying the name of the global group.

level = 0
An integer that specifies the data in the members parameter. May be 0 or 3.

members
A sequence (for example, list or tuple) of dictionaries, each of which contains data that corresponds to one of the LOCALGROUP_MEMBERS_INFO structures.

NetMessageBufferSend()

Sends a string to a registered message alias.

NetMessageBufferSend(domain, userName, fromName, message)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

userName
The username or message alias to which the message should be sent.

fromName
A string that specifies the username or message alias from whom the message is from, or None for the logged-in user.

message
A string containing the message text.

NetServerEnum

Retrieves information about all servers of a specific type

entries, total, resume = NetServerEnum(serverName, level, serverTypes=win32netcon.SV_TYPE_ALL, resume = 0, len=4096)

Parameters

serverName
The name of the server to execute on or None for the current machine.

level
An integer specifying the level of information requested; can be 101 or 102.

serverTypes
A bitmask of flags indicating the types of servers to list. A list of the common flags is presented here; please refer to the Win32 documentation for more details.

SV_TYPE_WORKSTATION
All Internet workstations.
SV_TYPE_SERVER
All Internet servers.
SV_TYPE_SQLSERVER
Any server running with Microsoft SQL Server.
SV_TYPE_DOMAIN_CTRL
Primary domain controller.
SV_TYPE_DOMAIN_BAKCTRL
Backup domain controller.
SV_TYPE_TIMESOURCE
Server running the time-source service.
SV_TYPE_PRINT
Server sharing print queue.
SV_TYPE_DIALIN
Server running dial-in service.
SV_TYPE_NT
Windows NT (either workstation or server).
SV_TYPE_SERVER_NT
Windows NT nondomain controller server.
SV_TYPE_DOMAIN_MASTER
Server running the domain master browser.
SV_TYPE_DOMAIN_ENUM
Primary domain.
SV_TYPE_WINDOWS
Windows 95 or later.
SV_TYPE_ALL
All servers.

resume
A value that controls the iteration when there are many servers to list. Zero should be passed the first time it's called, and while a non-zero resume result is returned from the function, it can be called again with the new resume value to obtain the rest of the servers.

len = 4096
A hint to the Win32 function about how much data to allocate. See the Win32 documentation for more details.

Result

The result is a tuple with the following items:

entries
A list of dictionaries, each of the format define in one of the SERVER_INFO structures depending on the level parameter, one for each server returned.

total
The total number of items left to read before making the call. Thus, totallen (entries) are the number of entries left to read after this call.

resume
A resume handle that can obtain the next set of users. When resume is zero, there are no more items to read.

NetServerGetInfo

Retrieves information about a particular server.

data = NetServerGetInfo(serverName, level)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

level
An integer that specifies the data returned by the function. May be 100, 101, or 102 on all platforms, 1 or 50 on Windows 95/98, or 402 or 403 for Windows 2000.

Result

The result is a dictionary in the format of one of the SERVER_INFO structures, depending on the level parameter.

NetServerSetInfo()

Sets information about a particular server.

NetServerSetInfo(serverName, level, data)

Parameters

serverName
A string-specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

level
An integer that specifies the data in the data parameter. May be one of 100, 101, 102, 402, or 403.

data
A dictionary with the data for the server. The data is in the format of one of the SERVER_INFO structures, depending on the level parameter.

NetShareAdd()

Adds a server resource.

NetShareAdd(serverName, level, data)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

level
An integer that specifies the data in the data parameter. May be 2 or 502.

data
A dictionary with the data for the server resource. The data is in the format of one of the SHARE_INFO structures, depending on the level parameter.

NetShareDel()

Deletes a server resource.

NetShareDel(serverName, networkName)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

networkName
A string specifying the resource name to be deleted.

NetShareCheck

Checks if server is sharing a device.

result, type = NetShareCheck(serverName, deviceName)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

deviceName
A string specifying the name of the device to check for shared access

Result

result
true if the device is shared, otherwise false.

type
If result is true, indicates the type of device, and may be one of the following values:

win32net.STYPE_DISKTREE
The device is a shared disk drive.
win32net.STYPE_PRINTQ
The device is a shared print queue.
win32net.STYPE_DEVICE
The device is a shared communications device.
win32net.STYPE_IPC
An interprocess communication device.
win32net.STYPE_SPECIAL
A special device.

NetShareEnum

Retrieves information about each shared resource on a server.

entries, total, resume = NetShareEnum(serverName, level, resume = 0, len=4096)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

level
An integer that specifies the level of the data to be returned; may be 0, 1, 2, or 502.

resume
A value that controls the iteration when there are many servers to list. Zero should be passed the first time it's called, and while a non-zero resume result is returned from the function, it can be called again with the new resume value to obtain the rest of the servers.

len = 4096
A hint to the Win32 function about much data to allocate. See the Win32 documentation for more details.

Result

The result is a tuple with the following items:

entries
A list of dictionaries in the format of one of the SHARE_INFO structures, depending on the level parameter, one for each resource returned.

total
The total number of items left to read before making the call. Thus, total-len(entries) are the number of entries left to read after this call.

resume
A resume handle, that can be used to obtain the next set of users. When resume is zero, there are no more items to read.

NetShareGetInfo

Retrieves information about a particular share on a server.

data = NetShareGetInfo(serverName, networkName, level)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

networkName
A string specifying the network name of the share on which to return information.

level
An integer that specifies the data returned by the function. May be 0, 1, 2, 501, 502, or 1005.

Result

The result is a dictionary in the format of one of the SHARE_INFO structures, depending on the level parameter.

NetShareSetInfo()

Sets information about a particular share on a server.

NetShareSetInfo(serverName, networkName, level, data)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

networkName
A string specifying the network name to set.

level
An integer that specifies the data in the data parameter. May be 1, 2, 502, 1004, 1006, or 1501.

data
A dictionary with the data for the server. The data is in the format of one of the SHARE_INFO structures, depending on the level parameter.

NetUserAdd()

Creates a new user account.

NetUserAdd(serverName, level, data)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

level
An integer that specifies the data in the data parameter. May be 1, 2, or 3.

data
A dictionary with the data for the server resource. The data must be in the format of the relevant USER_INFO structure, depending on the level parameter.

NetUserChangePassword()

Changes a user's password on the specified domain.

NetUserChangePassword(serverName, userName, oldPassword, newPassword)

Parameters

serverName
A string specifying the name of a remote server or domain on which the account is changed. If this parameter is None, the logon domain of the caller is used.

userName
The username for which the password is to be changed or None for the current user.

oldPassword
The user's old password.

newPassword
The user's new password.

NetUserEnum

Provides information about all user accounts on a server.

entries, total, resume = NetUserEnum(serverName, level, filter=win32netcon.FILTER_ACCOUNT_NORMAL resume = 0, len=4096)

Parameters

serverName
The name of the server to execute on or None for the current machine.

level
An integer specifying the level of information requested. This can be 0, 1, 2, 3, 10, 11, or 20.

filter
Specifies the account types to enumerate, which may be one of the following values:

FILTER_TEMP_DUPLICATE_ACCOUNT
Enumerates local user account data on a domain controller.
FILTER_NORMAL_ACCOUNT
Enumerates global user account data on a computer.
FILTER_INTERDOMAIN_TRUST_ACCOUNT
Enumerates domain trust account data on a domain controller.
FILTER_WORKSTATION_TRUST_ACCOUNT
Enumerates workstation or member server account data on a domain controller.
FILTER_SERVER_TRUST_ACCOUNT
Enumerates domain-controller account data on a domain controller.

Result

The result is a tuple with the following items:

entries
A list of dictionaries, one for each user returned. Each dictionary is in the format specified by the relevant USER_INFO structure, depending on the level parameter.

total
The total number of items left to read before making the call. Thus, total-len(entries) are the number of entries left to read after this call.

resume
A resume handle, that can be used to obtain the next set of users. When resume is zero, there are no more items to read.

NetUserGetInfo

Retrieves information about a particular user account on a server.

data = NetUserGetInfo(serverName, userName, level)

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

networkName
A string specifying the network name of the share on which to return information.

level
An integer that specifies the data returned by the function. May be 0, 1, 2, 3, 10, 11, or 20.

Result

The result is a dictionary in the format of one of the USER_INFO structures, depending on the level parameter.

NetUserSetInfo()

Sets information about a particular user account on a server.

NetUserSetInfo(serverName, userName, level, data)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

userName
A string specifying the username for which the information is to be set.

level
An integer that specifies the data in the data parameter. May be any level corresponding to a USER_INFO structure.

data
A dictionary with the data for the server. The data is in the format of one of the USER_INFO structures, depending on the level parameter.

NetUserDel()

Deletes a user account from a server.

NetUserDel(serverName, userName)

Parameters

serverName
A string specifying the name of the remote server on which the function is to execute. If this parameter is None, the local computer is used.

userName
A string specifying the username to be deleted.

USER_INFO Structures

USER_INFO_0

Attribute NameDescription
nameSpecifies the name of the user account. For the win32net. NetUserSetInfo () function, this member specifies the new username. The number of characters in the name can't exceed the value of win32netcon. UNLEN.

USER_INFO_1

Attribute NameDescription
nameA string that specifies the name of the user account. For the win32net. NetUserSetInfo () function, this member specifies the new username. The number of characters in the name can't exceed the value of win32netcon.UNLEN.
passwordA string that specifies the password of the user.
password_ageAn integer that specifies the number of seconds that have elapsed since the password member was last changed.

Attribute NameDescription
privOne of three integer values specifying the level of privilege assigned the name member. May be one of win32netcon.USER_PRIV_GUEST, win32netcon.USER_PRIV_USER, or win32netcon.USER_PRIV_ADMIN.
home_dirA string specifying the path of the home directory for the user. May be None.
commentA string with a comment for the user, or None.
flagsAn integer containing values that determine several features. May be any combination of the win32netcon.UF_flags.
script_pathA string that specifies the path for the user's logon script file. The script file can be a .cmd file, an .exe file, or a .bat file. May also be None.

USER_INFO_2

Attribute NameDescription
nameA string that specifies the name of the user account. For the win32net.NetUserSetInfo() function, this member specifies the new username. The number of characters in the name can't exceed the value of win32netcon.UNLEN.
passwordA string that specifies the password of the user.
password_ageAn integer that specifies the number of second that have elapsed since the password member was last changed.
privOne of three integer values specifying the level of privilege assigned the name member. May be one of win32netcon.USER_PRIV_GUEST,win32netcon.USER_PRIV_USER, or win32netcon.USER_PRIV_ADMIN.
home_dirA string specifying the path of the home directory for the user. May be None.
commentA string with a comment for the user, or None.
flagsAn integer containing values that determine several features. May be any combination of the win32netcon.UF_flags.
script_pathA string that specifies the path for the user's logon script file. The script file can be a .cmd file, an .exe file, or a .bat file. May also be None.
auth_flagsSpecifies an unsigned long integer that contains values that specify the user's operator privileges. May be one of the win32netcon.AF_constants.
full_nameA string containing the full name of the user.
usr_commentA string that contains a user comment, or None.
parmsA string that's set aside for use by applications, including Microsoft applications. Don't modify this.
workstationsA string containing the names of workstations from which the user can log on. As many as eight names can be specified, and each is separated by a comma. None indicates there is no restriction.

Attribute NameDescription
last_logonThe number of seconds since Jan. 1, 1970 since the last logon by the user.
last_logoffThe number of seconds since Jan. 1, 1970 since the last logoff by the user, or zero if this information isn't known.
acct_expiresSpecifies when the account will expire. Stored as the number of seconds since Jan. 1, 1970, and a value of win32netcon.TIMEO_FOREVER indicates the account never expires.
max_storageAn integer that specifies the maximum amount of disk space the user can use. Use the value specified in win32netcon. USER_MAXSTORAGE_UNLIMITED to employ all available disk space.
units_per_weekSpecifies the number of equal-length time units into which the week is divided in order to compute the length of the bit string in the logon_hours member.
logon_hoursA 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week in Greenwich Mean Time (GMT). The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. Note that bit 0 in word 0 represents Sunday from 0:00 to 0:59 only if you are in the GMT time zone. In all other cases you must adjust the bits according to your time zone offset (for example, GMT minus eight hours for Pacific Standard Time). None if there is no restriction.
bad_pw_countSpecifies the number of times the user tried to log on to the account using an incorrect password. A value of 0xFFFFFFFF indicates the value is unknown.
num_logonsCounts the number of successful times the user tried to log on to this account. A value of 0xFFFFFFFF indicates that the value is unknown.
logon_serverA string that contains the name of the server to which logon requests are sent. Server names should be preceded by two blackslashes (\\). When the server name is indicated by an asterisk (\\*), the logon request can be handled by any logon server. None indicates that requests are sent to the domain controller.
country_codeSpecifies the country code for the user's language of choice.
code_pageSpecifies the code page for the user's language of choice.

USER_INFO_3

Attribute NameDescription
nameA string that specifies the name of the user account. For the win32net.NetUserSetInfo () function, this member specifies the new username. The number of characters in the name can't exceed the value of win32netcon.UNLEN.
passwordA string that specifies the password of the user.
password_ageA integer that specifies the number of seconds have elapsed since the password member was last changed.

Attribute NameDescription
privOne of three integer values specifying the level of privilege assigned the name member. May be one of win32netcon.USER_PRIV_GUEST, win32netcon.USER_PRIV_USER, or win32netcon.USER_PRIV_ADMIN.
home_dirA string specifying the path of the home directory for the user. May be None.
commentA string with a comment for the user, or None.
flagsAn integer containing values that determine several features. May be any combination of the win32netcon.UF_flags.
script_pathA string that specifies the path for the user's logon script file. The script file can be a .cmd file, an .exe file, or a .bat file. May also be None.
auth_flagsSpecifies an unsigned long integer that contains values that specify the user's operator privileges. May be one of the win32netcon.AF_constants.
full_nameA string containing the full name of the user.
usr_commentA string that contains a user comment, or None.
parmsA string that's set aside for use by applications, including Microsoft applications. Don't modify this.
workstationsA string containing the names of workstations from which the user can log on. As many as eight names can be specified, and each is separated by a comma. None indicates there is no restriction.
last_logonThe number of seconds since Jan. 1, 1970 since the last logon by the user.
last_logoffThe number of seconds since Jan. 1, 1970 since the last logoff by the user, or zero if this information isn't known.
acct_expiresSpecifies when the account will expire. Stored as the number of seconds since Jan. 1, 1970, and a value of win32netcon.TIMEQ_FOREVER indicates the account never expires.
max_storageAn integer that specifies the maximum amount of disk space the user can use. Use the value specified in win32netcon.USER_MAXSTORAGE_UNLIMITED to employ all available disk space.
units_per_weekSpecifies the number of equal-length time units into which the week is divided in order to compute the length of the bit string in the logon_hours member.
logon_hoursA 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week, in Greenwich Mean Time (GMT). The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. Note that bit 0 in word 0 represents Sunday from 0:00 to 0:59 only if you are in the GMT time zone. In all other cases you must adjust the bits according to your time zone offset (for example, GMT minus eight hours for Pacific Standard Time). None if there is no restriction.

Attribute NameDescription
bad_pw_countAn integer that specifies the number of times the user tried to log on to the account using an incorrect password. A value of 0xFFFFFFFF indicates the value is unknown.
num_logonsCounts the number of successful times the user tried to log on to this account. A value of 0xFFFFFFFF indicates the value is unknown.
logon_serverA string that contains the name of the server to which logon requests are sent. Server names should be preceded by two backslashes (\\). When the server name is indicated by an asterisk (\\*), the logon request can be handled by any logon server. None indicates that requests are sent to the domain controller.
country_codeAn integer that specifies the country code for the user's language of choice.
code_pageAn integer that specifies the code page for the user's language of choice.
user_idAn integer that specifies the relative ID (RID) of the user. The RID is determined by the Security Account Manager (SAM) when the user is created. It uniquely defines this user account to SAM within the domain.
primary_group_idAn integer that specifies the RID of the primary global group for this user. For win32net.NetUserAdd(), this member must be win32netcon.DOMAIN_GROUP_RID_USERS. For win32net. NetUserSetInfo(), this member must be the RID of a global group in which the user is enrolled.
profileA string that specifies the path to the user's profile. This value can be None, a local absolute path, or a UNC path.
home_dir_driveA string that specifies the drive letter assigned to the user's home directory for logon purposes.
password_expiredAn integer that determines whether the password of the user has expired. The win32net.NetUserGetInfo() and win32net.NetUserEnum() functions return zero if the password has not expired (and nonzero if it has). For win32net.NetUserAdd() or win32net.NetUserSetInfo(), specify nonzero to indicate that the user must change password at next logon. For win32net.NetUserSetInfo(), specify zero to turn off the message indicating that the user must change password at next logon. Note that you can't specify zero to negate the expiration of a password that has already expired.

USER_INFO_10

Attribute NameDescription
nameA string that specifies the name of the user account. The number of characters in the name can't exceed the value of win32netcon.UNLEN.
commentA string with a comment for the user, or None.
full_nameA string containing the full name of the user.
usr_commentA string that contains a user comment, or None.

USER_INFO_11

Attribute NameDescription
nameA string that specifies the name of the user account. The number of characters in the name can't exceed the value of win32netcon.UNLEN.
full_nameA string containing the full name of the user.
commentA string with a comment for the user, or None.
usr_commentA string that contains a user comment, or None.
privOne of three integer values specifying the level of privilege assigned the name member. May be one of win32netcon.USER_PRIV_GUEST, win32netcon.USER_PRIV_USER, or win32netcon.USER_PRIV_ADMIN.
auth_flagsSpecifies an unsigned long integer that contains values that specify the user's operator privileges. May be one of the win32netcon.AF_ constants.
password_ageAn integer that specifies the number of seconds elapsed since the password member was last changed.
home_dirA string specifying the path of the home directory for the user. May be None.
parmsA string that's set aside for use by applications, including Microsoft applications. Don't modify this.
last_logonThe number of seconds since Jan. 1, 1970 since the last logon by the user.
last_logoffThe number of seconds since Jan. 1, 1970 since the last logoff by the user, or zero if this information isn't known.
bad_pw_countAn integer that specifies the number of times the user tried to log on to the account using an incorrect password. A value of 0xFFFFFFFF indicates the value is unknown.
num_logonsCounts the number of successful times the user tried to log on to this account. A value of 0xFFFFFFFF indicates the value is unknown.
logon_serverA string that contains the name of the server to which logon requests are sent. Server names should be preceded by two backslashes (\\). When the server name is indicated by an asterisk (\\*), the logon request can be handled by any logon server. None indicates that requests are sent to the domain controller.
country_codeAn integer that specifies the country code for the user's language of choice.
workstationsA string containing the names of workstations from which the user can log on. As many as eight names can be specified, and each is separated by a comma. None indicates there is no restriction.
max_storageAn integer that specifies the maximum amount of disk space the user can use. Use the value specified in win32netcon.USER_MAXSTORAGE_UNLIMITED to use all available disk space.
units_per_weekSpecifies the number of equal-length time units into which the week is divided in order to compute the length of the bit string in the logon_hours member.

(table continued on next page)

(table continued from previous page)

Attribute NameDescription
logon_hoursA 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week, in Greenwich Mean Time (GMT). The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. Note that bit 0 in word 0 represents Sunday from 0:00 to 0:59 only if you are in the GMT time zone. In all other cases you must adjust the bits according to your time zone offset (for example, GMT minus eight hours for Pacific Standard Time). None if there is no restriction.
code_pageAn integer that specifies the code page for the user's language of choice.

USER_INFO_20

Attribute NameDescription
nameA string that specifies the name of the user account. The number of characters in the name can't exceed the value of win32netcon.UNLEN.
full_nameA string containing the full name of the user.
commentA string with a comment for the user, or None.
flagsAn integer containing values that determine several features. May be any combination of the win32netcon.UF_ flags.
user_idAn integer that specifies the relative ID (RID) of the user. The RID is determined by the Security Account Manager (SAM) when the user is created. It uniquely defines this user account to SAM within the domain.

USER_INFO_1003

Attribute NameDescription
passwordA string that specifies the password for the user.

USER_INFO_1005

Attribute NameDescription
privOne of three integer values specifying the level of privilege assigned the name member. May be one of win32netcon.USER_PRIV_GUEST, win32netcon.USER_PRIV_USER, or win32netcon.USER_PRIV_ADMIN.

USER_INFO_1006

Attribute NameDescription
home_dirA string specifying the path of the home directory for the user. May be None.

USER_INFO_1007

Attribute NameDescription
commentA string with a comment for the user or None.

USER_INFO_1008

Attribute NameDescription
flagsAn integer containing values that determine several features. May be any combination of the win32netcon.UF_ flags.

USER_INFO_1009

Attribute NameDescription
script_pathA string that specifies the path for the user's logon script file. The script file can be a .cmd file, an .exe file, or a .bat file. May also be None.

USER_INFO_1010

Attribute NameDescription
auth_flagsSpecifies an unsigned long integer that contains values that specify the user's operator privileges. May be one of the win32netcon.AF_ constants.

USER_INFO_1011

Attribute NameDescription
full_nameA string containing the full name of the user.

SERVER_INFO Structures

SERVER_INFO_100

Attribute NameDescription
platform_idAn integer that indicates the server platform.
nameA string indicating the name of the server.

SERVER_INFO_101

Attribute NameDescription
platform_idAn integer that indicates the server platform.
nameA string indicating the name of the server.

(table continued on next page)

(table continued from previous page)

Attribute NameDescription
version_majorSpecifies, in the least significant four bits of the byte, the major release version number of the operating system. The most significant four bits of the byte specifies the server type. The mask win32netcon.MAJOR_VERSION_MASK should be used to ensure correct results.
version_minorIndicates the minor release version number of the operating system.
typeDescribes the type of software the computer is running. This member can be one of the win32netcon.SV_TYPE_ constants.
commentA string containing a comment for the server, or None.

SERVER_INFO_102

Attribute NameDescription
platform_idAn integer that indicates the server platform.
nameA string indicating the name of the server.
version_majorSpecifies, in the least significant four bits of the byte, the major release version number of the operating system. The most significant four bits of the byte specifies the server type. The mask win32netcon.MAJOR_VERSION_MASK should be used to ensure correct results.
version_minorIndicates the minor release version number of the operating system.
typeDescribes the type of software the computer is running. This member can be one of the win32netcon.SV_TYPE_ constants.
commentA string containing a comment for the server or None.
usersAn integer that indicates the number of users who can attempt to log on to the system server. However, it's the license server that determines how many of these users can actually log on.
discIndicates the auto-disconnect time, in minutes. A session is disconnected if it's idle longer than the time specified. If the value is win32netcon.SV_NODISC, auto-disconnect isn't enabled.
hiddenDetermines whether the server is visible to other computers in the same network domain. This member can be either win32netcon.SV_VISIBLE or win32netcon.SV_HIDDEN.
announceAn integer that specifies the network announce rate in seconds. This rate determines how often the server is announced to other computers on the network.
anndeltaAn integer that specifies the delta value or change of the announce rate, in milliseconds. This value specifies how much the announce rate can vary from the time specified in the announce member.
licensesSpecifies the number of users per license. By default, this number is win32netcon.SV_USERS_PER_LICENSE.
userpathA string specifying the path to user directories.

SERVER_INFO_402

Attribute NameDescription
ulist_mtimeAn integer that indicates the last time (in seconds from 00:00:00, January 1,1970) the user list for servers running user-level security was modified.
glist_mtimeAn integer that indicates the last time (in seconds from 00:00:00, January 1,1970) the group list for servers running user-level security was modified.
alist_mtimeAn integer that indicates the last time (in seconds from 00:00:00, January 1,1970) the access control list for servers running user-level security was modified.
alertsA string holding a list of usernames. Each name is separated by a space.
securityAn integer that defines the security settings of the server; may be either win32netcon.SV_SHARESECURITY or win32netcon.SV_USERSECURITY.
numadminAn integer that specifies how many administrators a server can accommodate at the same time.
lanmaskAn integer that determines the order in which the network device drivers are served.
guestacctA string specifying the name of a reserved guest user account for a server. The constant win32netcon.UNLEN specifies the maximum number of characters in the string.
chdevsAn integer that specifies how many character-oriented devices can be shared on the server.
chdevqAn integer that specifies how many character-oriented device queues can coexist on the server.
chdevjobsAn integer that specifies how many character-oriented device jobs can be pending on a server.
connectionsAn integer that specifies the number of connections to share names allowed on a server.
sharesAn integer that specifies the number of share names a server can accommodate.
openfilesAn integer that specifies the number of files that can be open at once.
sessopensAn integer that specifies the number of files that can be open in one session.
sessvcsAn integer that specifies the maximum number of virtual circuits per client.
sessreqsAn integer that specifies the number of simultaneous requests a client can make on any virtual circuit.
opensearchAn integer that specifies the number of searches that can be open at once.
activelocksAn integer that specifies the number of file locks that can be active at the same time.

(table continued on next page)

(table continued from previous page)

Attribute NameDescription
numreqbufAn integer that specifies the number of server buffers provided.
sizreqbufAn integer that specifies the size, in bytes, of each server buffer.
sizreqbufAn integer that specifies the size, in bytes, of each server buffer.
numbigbufAn integer that specifies the number of 64-KB server buffers provided.
numfiletasksAn integer that specifies the number of processes that can access the operating system at one time.
alertschedAn integer that specifies the interval, in seconds, at which to notify an administrator of a network event.
erroralertAn integer that specifies how many entries can be written to the errorlog file during an interval specified in the sv402_alertsched before notifying an administrator.
logonalertAn integer that specifies how many invalid logon attempts to allow a user before notifying an administrator.
accessalertAn integer that specifies the number of invalid attempts to access a file to allow before notifying an administrator.
diskalertAn integer that specifies the number of kilobytes of free disk space remaining on the disk before the system sends a message to notify an administrator that free space for a disk is low.
netioalertAn integer that specifies, in tenths of a percent, the network I/O error ratio allowable before notifying an administrator.
maxauditszAn integer that specifies, in kilobytes, the maximum size of the audit file. The audit file traces activity of the user.
srvheuristicsA string of flags that control operations on a server.

SERVER_INFO_403

Attribute NameDescription
ulist_mtimeAn integer that indicates the last time (in seconds from 00:00:00, January 1,1970) the user list for servers running user-level security was modified.
glist_mtimeAn integer that indicates the last time (in seconds from 00:00:00, January 1,1970) the group list for servers running user-level security was modified.
alist_mtimeAn integer that indicates the last time (in seconds from 00:00:00, January 1,1970) the access control list for servers running user-level security was modified.
alertsA string holding a list of usernames. Each name is separated by a space.
securityAn integer that defines the security settings of the server; may be either win32netcon.SV_SHARESECURITY or win32netcon.SV_USERSECURITY.
numadminAn integer that specifies how many administrators a server can accommodate at the same time.

(table continued on next page)

(table continued from previous page)

Attribute NameDescription
lanmaskAn integer that determines the order in which the network device drivers are served.
guestacctA string specifying the name of a reserved guest user account for a server. The constant win32netcon.UNLEN specifies the maximum number of characters in the string.
chdevsAn integer that specifies how many character-oriented devices can be shared on the server.
chdevqAn integer that specifies how many character-oriented device queues can coexist on the server.
chdevjobsAn integer that specifies how many character-oriented device jobs can be pending on a server.
connectionsAn integer that specifies the number of connections to share names allowed on a server.
sharesAn integer that specifies the number of share names a server can accommodate.
openfilesAn integer that specifies the number of files that can be open at once.
sessopensAn integer that specifies the number of files that can be open in one session.
sessvcsAn integer that specifies the maximum number of virtual circuits per client.
sessreqsAn integer that specifies the number of simultaneous requests a client can make on any virtual circuit.
opensearchAn integer that specifies the number of searches that can be open at once.
activelocksAn integer that specifies the number of file locks that can be active at the same time.
numreqbufAn integer that specifies the number of server buffers provided.
sizreqbufAn integer that specifies the size, in bytes, of each server buffer.
sizreqbufAn integer that specifies the size, in bytes, of each server buffer.
numbigbufAn integer that specifies the number of 64-KB server buffers provided.
numfiletasksAn integer that specifies the number of processes that can access the operating system at one time.
alertschedAn integer that specifies the interval, in seconds, at which to notify an administrator of a network event.
erroralertAn integer that specifies how many entries can be written to the error log file during an interval specified in the sv402_alertsched before notifying an administrator.
logonalertAn integer that specifies how many invalid logon attempts to allow a user before notifying an administrator.
accessalertAn integer that specifies the number of invalid attempts to access a file to allow before notifying an administrator.

(table continued on next page)

(table continued from previous page)

Attribute NameDescription
diskalertAn integer that specifies the number of kilobytes of free disk space remaining on the disk before the system sends a message to notify an administrator that free space for a disk is low.
netioalertAn integer that specifies, in tenths of a percent, the network I/O error ratio allowable before notifying an administrator.
maxauditszAn integer that specifies, in kilobytes, the maximum size of the audit file. The audit file traces activity of the user.
srvheuristicsA string of flags that control operations on a server.
auditedeventsAn integer that specifies the audit event control mask.
autoprofileControls the action of the server on the profile. May be either win32netcon.SW_AUTOPROF_LOAD_MASK or win32netcon.SW_AUTOPROF_SAVE_MASK.
autopathA string containing the path for the profile.

SERVER_INFO_502

Attribute NameDescription
sessopensAn integer that specifies the number of files that can be open in one session.
sessvcsAn integer that specifies the maximum number of virtual circuits per client.
opensearchAn integer that specifies the number of search operations that can be carried out simultaneously.
sizreqbufAn integer that specifies the size, in bytes, of each server buffer.
initworkitemsAn integer that specifies the initial number of receive buffers, or work items, used by the server. Allocating work items costs a certain amount of memory initially, but not as much as having to allocate additional buffers later.
maxworkitemsAn integer that specifies the maximum number of receive buffers, or work items, the server can allocate.
rawworkitemsAn integer that specifies the number of special work items for raw I/O the server uses. A larger value for this member can increase performance but costs more memory.
irpstacksizeAn integer that specifies the number of stack locations in IRPs allocated by the server.
maxrawbuflenAn integer that specifies the maximum raw mode buffer size.
sessusersAn integer that specifies the maximum number of users that can be logged on to a server using a single virtual circuit.
sessconnsAn integer that specifies the maximum number of tree connections that can be made on the server with one virtual circuit.
maxpagedmemoryusageAn integer that specifies the maximum size of pageable memory the server can have allocated at any time. Adjust this member if you want to administer memory quota control.

(table continued on next page)

(table continued from previous page)

Attribute NameDescription
maxnonpagedmemoryusageAn integer that specifies the maximum size of nonpaged memory the server can have allocated at any time. Adjust this member if you want to administer memory quota control.
enablesoftcompatAn undocumented integer member. Please see the Win32 SDK for more details.
enableforcedlogoffAn integer that specifies whether the server should force a client to disconnect, even if the client has open files, once the client's logon time has expired.
timesourceAn integer that specifies whether the server is a reliable time source.
acceptdownlevelapisAn integer that specifies whether the server will accept function calls from previous generation LAN Manager clients.
lmannounceAn integer that specifies the LAN Manager server announcement interval.

SERVER_INFO_503

Attribute NameDescription
sessopensAn integer that specifies the number of files that can be open in one session.
sessvcsAn integer that specifies the maximum number of virtual circuits per client.
opensearchAn integer that specifies the number of search operations that can be carried out simultaneously.
sizreqbufAn integer that specifies the size, in bytes, of each server buffer.
initworkitemsAn integer that specifies the initial number of receive buffers, or work items, used by the server. Allocating work items costs a certain amount of memory initially, but not as much as having to allocate additional buffers later.
maxworkitemsAn integer that specifies the maximum number of receive buffers, or work items, the server can allocate.
rawworkitemsAn integer that specifies the number of special work items for raw I/O the server uses. A larger value for this member can increase performance but costs more memory.
irpstacksizeAn integer that specifies the number of stack locations in IRPs allocated by the server.
maxrawbuflenAn integer that specifies the maximum raw mode buffer size.
sessusersAn integer that specifies the maximum number of users that can be logged on to a server using a single virtual circuit.
sessconnsAn integer that specifies the maximum number of tree connections that can be made on the server using a single virtual circuit.

(table continued on next page)

(table continued from previous page)

Attribute NameDescription
maxpagedmemoryusageAn integer that specifies the maximum size of pageable memory the server can have allocated at any time. Adjust this member if you want to administer memory quota control.
maxnonpagedmemoryusageAn integer that specifies the maximum size of nonpaged memory the server can have allocated at any time. Adjust this member if you want to administer memory quota control.
enablesoftcompatAn undocumented integer member. Please see the Win32 API documentation for more details.
enableforcedlogoffAn integer that specifies whether the server should force a client to disconnect, even if the client has open files, once the client's logon time has expired.
timesourceAn integer that specifies whether the server is a reliable time source.
acceptdownlevelapisAn integer that specifies whether the server will accept function calls from previous generation LAN Manager clients.
lmannounceAn integer that specifies the LAN Manager server announcement interval.
domainA string that specifies the name of the server's domain.
maxcopyreadlenAn undocumented integer member. Please see the Win32 API documentation for more details.
maxcopywritelenAn undocumented integer member. Please see the Win32 API documentation for more details.
minkeepsearchAn undocumented integer member. Please see the Win32 API documentation for more details.
maxkeepsearchAn integer that specifies the length of time the server retains information about directory searches that have not ended.
minkeepcomplsearchAn undocumented integer member. Please see the Win32 API documentation for more details.
maxkeepcomplsearchAn undocumented integer member. Please see the Win32 API documentation for more details.
threadcountaddAn undocumented integer member. Please see the Win32 API documentation for more details.
numblockthreadsAn undocumented integer member. Please see the Win32 API documentation for more details.
scavtimeoutAn integer that specifies the time the scavenger remains idle before waking up to service requests. A smaller value for this member improves the response of the server to various events but costs CPU cycles.
minrcvqueueAn integer that specifies the minimum number of free receive work items needed by the server before it begins allocating more. A larger value for this member helps ensure there are always work items available, but a value that is too large is simply inefficient.

(table continued on next page)

(table continued from previous page)

Attribute NameDescription
minfreeworkitemsSpecifies the minimum number of available receive work items needed for the server to begin processing a server message block.
xactmemsizeAn integer that specifies the size of the shared memory region that processes server functions.
threadpriorityAn integer that specifies the priority of all server threads in relation to the base priority of the process. Higher priority can give better server performance at the cost of local responsiveness. Lower priority balances server needs with the needs of other processes on the system.
maxmpxctAn integer that specifies the maximum number of simultaneous requests any one client can send to the server. For example, 10 means you can have 10 unanswered requests at the server. When any single client has 10 requests queued within the server, the client must wait for a server response before sending another request.
oplockbreakwaitAn integer that specifies the time to wait before timing out an opportunistic lock break request.
oplockbreakresponsewaitAn integer that specifies the time to wait before timing out an opportunistic lock break request.
enableoplocksAn integer that specifies whether the server allows clients to use opportunistic locks on files. Opportunistic locks are a significant performance enhancement, but have the potential to cause lost cached data on some networks, particularly wide-area networks.
enableoplockforcecloseAn undocumented integer member. Please see the Win32 API documentation for more details.
enablefcbopensAn integer that specifies whether several MS-DOS file control blocks (FCBs) are placed in a single location accessible by the server. This saves resources on the server.
enablerawAn integer that specifies whether the server processes raw server message blocks (SMBs). If enabled, this allows more data to transfer per transaction and also improves performance. However, it's possible that processing raw SMBs can impede performance on certain networks. The server maintains the value of this member.
enablesharednetdrivesAn integer that specifies whether the server allows redirected server drives to be shared.
minfreeconnectionsAn integer that specifies the minimum number of connection structures the server sets aside to handle bursts of requests by clients to connect to the server.
maxfreeconnectionsAn integer that specifies the maximum number of connection structures the server sets aside to handle bursts of requests by clients to connect to the server.

GROUP_INFO Structures

GROUP_INFO_0

Attribute NameDescription
nameA string containing the group name.

GROUP_INFO_1

Attribute NameDescription
nameA string containing the group name.
commentA string containing a comment for the group.

GROUP_INFO_2

Attribute NameDescription
nameA string containing the group name.
commentA string containing a comment for the group.
group_idAn integer value that contains the relative identifier of the global group.
attributesAn integer that holds the attributes for the group.

GROUP_INFO_1002

Attribute NameDescription
commentA string containing a comment for the group.

GROUP_INFO_1005

Attribute NameDescription
attributesAn integer that holds the attributes for the group.

GROUP_USERS_INFO Structures

GROUP_USERS_INFO_1

Attribute NameDescription
nameA string containing the group name.

LOCALGROUP_USERS_INFO Structures

LOCALGROUP_USERS_INFO_0

Attribute NameDescription
nameA string containing the name of a local group to which the user belongs.

LOCALGROUP_INFO Structures

LOCALGROUP_INFO_0

Attribute NameDescription
nameA string containing the local group name.

LOCALGROUP_INFO_1

Attribute NameDescription
nameA string containing the local group name.
commentA string containing a comment for the local group.

LOCALGROUP_INFO_1002

Attribute NameDescription
commentA string containing a comment for the local group.

LOCALGROUP_MEMBERS_INFO Structures

LOCALGROUP_MEMBERS_INFO_0

Attribute NameDescription
sidA PySID object identifying the user.

LOCALGROUP_MEMBERS_INFO_1

Attribute NameDescription
sidA PySID object identifying the user.
sidusageSpecifies the account type associated with the sid element. May be one of ntsecuritycon.SidTypeUser, ntsecuritycon.SidTypeGroup, ntsecuritycon.SidTypeWellKnownGroup, ntsecuritycon.SidTypeDeletedAccount, or ntsecuritycon.SidTypeUnknown.
nameThe account name of the local group member identified by the sid.

LOCALGROUP_MEMBERS_INFO_2

Attribute NameDescription
sidA PySID object identifying the user.
sidusageSpecifies the account type associated with the sid element.
domainandnameThe domain and account name of the local group member identified by the sid.

LOCALGROUP_MEMBERS_INFO_3

Attribute NameDescription
domainandnameThe domain and account name of the local group member identified by the sid.


Back



Python Programming On Win32. Help for Windows Programmers
Python Programming on WIN32: Help for Windows Programmers
ISBN: 1565926218
EAN: 2147483647
Year: 1999
Pages: 35

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net