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.
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.
__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).
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.
__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.
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().
There are no methods.
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.
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)
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.
The result is a Python interface object, the exact type of which is determined by the iid parameter.
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()
No parameters.
Equivalent to CoInitializeEx(pythoncom.COINIT_APARTMENTTHREADED). See CoInitializeEx() for more details.
CoInitializeEx( ) |
|
|
|
Initializes COM for the calling thread.
CoIntializeEx(flags)
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.
There’s no need to call this function for the Python thread that first imports the pythoncom module. Please see Appendix D, 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()
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)
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.
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.
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)
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.
The result is a Python COM interface object, the exact type of which is determined by the iid parameter.
When paired with CoMarshalInterThreadInterfaceInStream(), programs can easily and reliably marshal a COM interface object to another thread in the same process. See Appendix D for further details.
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)
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 (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.
Parameters
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)
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)
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 GetPriorityClass() 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 be 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.
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)
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.
An integer with the requested system metric.
GetDomainName( ) |
|
|
|
Retrieves the name of the domain to which the current computer belongs.
name = GetDomainName()
No parameters.
The result is a string with the current domain name.
GetUserName( ) |
|
|
|
Retrieves the username for the current thread.
name = GetUserName()
No parameters.
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()
No parameters.
The result is a string with the computer name.
InitiateSystemShutdown( ) |
|
|
|
Initiates a shutdown and optional restart of the specified computer.
InitiateSystemShutdown(machineName, message, timeout, bForceAppsClosed, bReboot)
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.
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)
machineName
A string that specifies the name of the computer on which to abort the shutdown or None for the local computer.
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()
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()
The result is an integer containing the Win32 process ID. Until the process terminates, this ID uniquely identifies the process to the system.
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)
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.
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)
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.
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_ABANDONED_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)
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 handle is 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
A WM_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_MOUSEBUTTON
A 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.
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)
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.
The result is a PyHANDLE object referencing the requested object.
SetEvent( ) |
|
|
|
Sets the state of the specified event object to signaled.
SetEvent(handle)
handle
The handle to the object to signal.
ResetEvent( ) |
|
|
|
Sets the state of the specified event object to nonsignaled.
ResetEvent(handle)
handle
The handle to the object to reset.
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)
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)
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.
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)
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.
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.
This object has no methods.
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.
EventID
An integer event ID, 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 ID |
Event Type |
Message Text |
1 to 9 |
Error |
%1 |
1 to 9 |
Information |
%1 |
1 to 9 |
Success |
%1 |
1 to 9 |
Warning |
%1 |
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)
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.GENERIC_WRITE 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 lazy-write 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.
A PyHANDLE object to the file.
ReadFile( ) |
|
|
|
Reads data from an open file.
errCode, data = ReadFile(FileHandle, Size, Overlapped)
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.
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)
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.
errCode
Either or ERROR_IO_PENDING.
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)
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.
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)
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.
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.
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)
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 process 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.
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)
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)
handle
A PyHANDLE or integer that represents the handle to the process for which the affinity mask is to be retrieved.
processMask
An integer representing the affinity mask for the specified process.
systemMask
An integer representing the affinity mask for the system.
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)
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.
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)
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.
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)
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.
There are a number of Python modules related to Windows NT Services.
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)
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.
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)
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.
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)
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)
serviceName
The name of the service to stop.
machineName
The name of the machine on which to stop the service.
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)
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.
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.
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)
handle
A handle obtained from win32service.OpenSCManager(), win32service.OpenService(), or win32service.CreateService().
ControlService( ) |
|
|
|
Sends control requests to a service.
status = ControlService(handle, code)
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.
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)
handle
Handle to the service, as obtained from win32service.OpenService().
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)
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.
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, for more information.
LogMsg( ) |
|
|
|
Logs a specific message to the Event Log.
LogMsg(errorType, eventId, inserts = ())
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)
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 ID |
Event Type |
Message Text |
0xFF |
Error |
%1 |
0x1000-PYS_SERVICE_STARTING |
Information |
The %1 service is starting %2. |
0x1002-PYS_SERVICE_STARTED |
Information |
The %1 service has started %2. |
0x1003-PYS_SERVICE_STOPPING |
Information |
The %1 service is stopping %2. |
0x1004-PYS_SERVICE_STOPPED |
Information |
The %1 service has stopped %2. |
1 to 9 |
Error |
%1 |
1 to 9 |
Information |
%1 |
1 to 9 |
Success |
%1 |
1 to 9 |
Warning |
%1 |
NetGroupGetInfo |
|
|
|
Retrieves information about a particular global group in the security database.
data = NetGroupGetInfo(serverName, groupName, 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.
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.
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)
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 (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.
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, total-len(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)
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 (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)
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)
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)
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)
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)
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)
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.
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, total-len(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)
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 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)
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 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)
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.
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, total-len(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)
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 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)
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)
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.
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, total-len(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)
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.
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)
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)
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)
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)
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
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)
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 how much data to allocate. See the Win32 documentation for more details.
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)
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.
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)
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)
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)
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)
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.
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.
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)
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)
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.
|
|
|
|
Attribute Name |
Description |
name |
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. |
Attribute Name |
Description |
name |
A 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. |
password |
A string that specifies the password of the user. |
password_age |
An integer that specifies the number of seconds that have elapsed since the password member was last changed. |
priv |
One 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_dir |
A string specifying the path of the home directory for the user. May be None. |
comment |
A string with a comment for the user, or None. |
flags |
An integer containing values that determine several features. May be any combination of the win32netcon.UF_ flags. |
script_path |
A 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. |
Attribute Name |
Description |
name |
A 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. |
password |
A string that specifies the password of the user. |
password_age |
An integer that specifies the number of seconds that have elapsed since the password member was last changed. |
priv |
One 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_dir |
A string specifying the path of the home directory for the user. May be None. |
comment |
A string with a comment for the user, or None. |
flags |
An integer containing values that determine several features. May be any combination of the win32netcon.UF_ flags. |
script_path |
A 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_flags |
Specifies an unsigned long integer that contains values that specify the user’s operator privileges. May be one of the win32netcon.AF_ constants. |
full_name |
A string containing the full name of the user. |
usr_comment |
A string that contains a user comment, or None. |
parms |
A string that’s set aside for use by applications, including Microsoft applications. Don’t modify this. |
workstations |
A 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_logon |
The number of seconds since Jan. 1, 1970 since the last logon by the user. |
last_logoff |
The number of seconds since Jan. 1, 1970 since the last logoff by the user, or zero if this information isn’t known. |
acct_expires |
Specifies 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_storage |
An 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_week |
Specifies the number of equal-length time units into which the week is divided in order to compute the length of the bit string in the logon_hours member. |
logon_hours |
A 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week 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 in word 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_count |
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_logons |
Counts the number of successful times the user tried to log on to this account. A value of 0xFFFFFFFF indicates that the value is unknown. |
logon_server |
A 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_code |
Specifies the country code for the user’s language of choice. |
code_page |
Specifies the code page for the user’s language of choice. |
Attribute Name |
Description |
name |
A 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. |
password |
A string that specifies the password of the user. |
password_age |
An integer that specifies the number of seconds have elapsed since the password member was last changed. |
priv |
One 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_dir |
A string specifying the path of the home directory for the user. May be None. |
comment |
A string with a comment for the user, or None. |
flags |
An integer containing values that determine several features. May be any combination of the win32netcon.UF_ flags. |
script_path |
A 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_flags |
Specifies an unsigned long integer that contains values that specify the user’s operator privileges. May be one of the win32netcon.AF_ constants. |
full_name |
A string containing the full name of the user. |
usr_comment |
A string that contains a user comment, or None. |
parms |
A string that’s set aside for use by applications, including Microsoft applications. Don’t modify this. |
workstations |
A 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_logon |
The number of seconds since Jan. 1, 1970 since the last logon by the user. |
last_logoff |
The number of seconds since Jan. 1, 1970 since the last logoff by the user, or zero if this information isn’t known. |
acct_expires |
Specifies 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_storage |
An 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_week |
Specifies the number of equal-length time units into which the week is divided in order to compute the length of the bit string in the logon_hours member. |
logon_hours |
A 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week, 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 in word 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_count |
An 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_logons |
Counts the number of successful times the user tried to log on to this account. A value of 0xFFFFFFFF indicates the value is unknown. |
logon_server |
A 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_code |
An integer that specifies the country code for the user’s language of choice. |
code_page |
An integer that specifies the code page for the user’s language of choice. |
user_id |
An 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_id |
An 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. |
profile |
A 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_drive |
A string that specifies the drive letter assigned to the user’s home directory for logon purposes. |
password_expired |
An 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. |
Attribute Name |
Description |
name |
A string that specifies the name of the user account. The number of characters in the name can’t exceed the value of win32netcon.UNLEN. |
comment |
A string with a comment for the user, or None. |
full_name |
A string containing the full name of the user. |
usr_comment |
A string that contains a user comment, or None. |
Attribute Name |
Description |
name |
A 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_name |
A string containing the full name of the user. |
comment |
A string with a comment for the user, or None. |
usr_comment |
A string that contains a user comment, or None. |
priv |
One 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_flags |
Specifies an unsigned long integer that contains values that specify the user’s operator privileges. May be one of the win32netcon.AF_ constants. |
password_age |
An integer that specifies the number of seconds elapsed since the password member was last changed. |
home_dir |
A string specifying the path of the home directory for the user. May be None. |
parms |
A string that’s set aside for use by applications, including Microsoft applications. Don’t modify this. |
last_logon |
The number of seconds since Jan. 1, 1970 since the last logon by the user. |
last_logoff |
The number of seconds since Jan. 1, 1970 since the last logoff by the user, or zero if this information isn’t known. |
bad_pw_count |
An 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_logons |
Counts the number of successful times the user tried to log on to this account. A value of 0xFFFFFFFF indicates the value is unknown. |
logon_server |
A 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_code |
An integer that specifies the country code for the user’s language of choice. |
workstations |
A 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_storage |
An 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_week |
Specifies the number of equal-length time units into which the week is divided in order to compute the length of the bit string in the logon_hours member. |
logon_hours |
A 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week, 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 in word 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_page |
An integer that specifies the code page for the user’s language of choice. |
Attribute Name |
Description |
name |
A 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_name |
A string containing the full name of the user. |
comment |
A string with a comment for the user, or None. |
flags |
An integer containing values that determine several features. May be any combination of the win32netcon.UF_ flags. |
user_id |
An 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. |
Attribute Name |
Description |
password |
A string that specifies the password for the user. |
Attribute Name |
Description |
priv |
One 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. |
Attribute Name |
Description |
home_dir |
A string specifying the path of the home directory for the user. May be None. |
Attribute Name |
Description |
comment |
A string with a comment for the user or None. |
Attribute Name |
Description |
flags |
An integer containing values that determine several features. May be any combination of the win32netcon.UF_ flags. |
Attribute Name |
Description |
script_path |
A 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. |
Attribute Name |
Description |
auth_flags |
Specifies an unsigned long integer that contains values that specify the user’s operator privileges. May be one of the win32netcon.AF_ constants. |
Attribute Name |
Description |
full_name |
A string containing the full name of the user. |
|
|
|
|
Attribute Name |
Description |
platform_id |
An integer that indicates the server platform. |
name |
A string indicating the name of the server. |
Attribute Name |
Description |
platform_id |
An integer that indicates the server platform. |
name |
A string indicating the name of the server. |
version_major |
Specifies, 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_minor |
Indicates the minor release version number of the operating system. |
type |
Describes the type of software the computer is running. This member can be one of the win32netcon.SV_TYPE_ constants. |
comment |
A string containing a comment for the server, or None. |
Attribute Name |
Description |
platform_id |
An integer that indicates the server platform. |
name |
A string indicating the name of the server. |
version_major |
Specifies, 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_minor |
Indicates the minor release version number of the operating system. |
type |
Describes the type of software the computer is running. This member can be one of the win32netcon.SV_TYPE_ constants. |
comment |
A string containing a comment for the server or None. |
users |
An 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. |
disc |
Indicates 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. |
hidden |
Determines 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. |
announce |
An integer that specifies the network announce rate in seconds. This rate determines how often the server is announced to other computers on the network. |
anndelta |
An 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. |
licenses |
Specifies the number of users per license. By default, this number is win32netcon.SV_USERS_PER_LICENSE. |
userpath |
A string specifying the path to user directories. |
Attribute Name |
Description |
ulist_mtime |
An 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_mtime |
An 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_mtime |
An 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. |
alerts |
A string holding a list of usernames. Each name is separated by a space. |
security |
An integer that defines the security settings of the server; may be either win32netcon.SV_SHARESECURITY or win32netcon.SV_USERSECURITY. |
numadmin |
An integer that specifies how many administrators a server can accommodate at the same time. |
lanmask |
An integer that determines the order in which the network device drivers are served. |
guestacct |
A 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. |
chdevs |
An integer that specifies how many character-oriented devices can be shared on the server. |
chdevq |
An integer that specifies how many character-oriented device queues can coexist on the server. |
chdevjobs |
An integer that specifies how many character-oriented device jobs can be pending on a server. |
connections |
An integer that specifies the number of connections to share names allowed on a server. |
shares |
An integer that specifies the number of share names a server can accommodate. |
openfiles |
An integer that specifies the number of files that can be open at once. |
sessopens |
An integer that specifies the number of files that can be open in one session. |
sessvcs |
An integer that specifies the maximum number of virtual circuits per client. |
sessreqs |
An integer that specifies the number of simultaneous requests a client can make on any virtual circuit. |
opensearch |
An integer that specifies the number of searches that can be open at once. |
activelocks |
An integer that specifies the number of file locks that can be active at the same time. |
numreqbuf |
An integer that specifies the number of server buffers provided. |
sizreqbuf |
An integer that specifies the size, in bytes, of each server buffer. |
sizreqbuf |
An integer that specifies the size, in bytes, of each server buffer. |
numbigbuf |
An integer that specifies the number of 64-KB server buffers provided. |
numfiletasks |
An integer that specifies the number of processes that can access the operating system at one time. |
alertsched |
An integer that specifies the interval, in seconds, at which to notify an administrator of a network event. |
erroralert |
An 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. |
logonalert |
An integer that specifies how many invalid logon attempts to allow a user before notifying an administrator. |
accessalert |
An integer that specifies the number of invalid attempts to access a file to allow before notifying an administrator. |
diskalert |
An 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. |
netioalert |
An integer that specifies, in tenths of a percent, the network I/O error ratio allowable before notifying an administrator. |
maxauditsz |
An integer that specifies, in kilobytes, the maximum size of the audit file. The audit file traces activity of the user. |
srvheuristics |
A string of flags that control operations on a server. |
Attribute Name |
Description |
ulist_mtime |
An 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_mtime |
An 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_mtime |
An 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. |
alerts |
A string holding a list of usernames. Each name is separated by a space. |
security |
An integer that defines the security settings of the server; may be either win32netcon.SV_SHARESECURITY or win32netcon.SV_USERSECURITY. |
numadmin |
An integer that specifies how many administrators a server can accommodate at the same time. |
lanmask |
An integer that determines the order in which the network device drivers are served. |
guestacct |
A 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. |
chdevs |
An integer that specifies how many character-oriented devices can be shared on the server. |
chdevq |
An integer that specifies how many character-oriented device queues can coexist on the server. |
chdevjobs |
An integer that specifies how many character-oriented device jobs can be pending on a server. |
connections |
An integer that specifies the number of connections to share names allowed on a server. |
shares |
An integer that specifies the number of share names a server can accommodate. |
openfiles |
An integer that specifies the number of files that can be open at once. |
sessopens |
An integer that specifies the number of files that can be open in one session. |
sessvcs |
An integer that specifies the maximum number of virtual circuits per client. |
sessreqs |
An integer that specifies the number of simultaneous requests a client can make on any virtual circuit. |
opensearch |
An integer that specifies the number of searches that can be open at once. |
activelocks |
An integer that specifies the number of file locks that can be active at the same time. |
numreqbuf |
An integer that specifies the number of server buffers provided. |
sizreqbuf |
An integer that specifies the size, in bytes, of each server buffer. |
sizreqbuf |
An integer that specifies the size, in bytes, of each server buffer. |
numbigbuf |
An integer that specifies the number of 64-KB server buffers provided. |
numfiletasks |
An integer that specifies the number of processes that can access the operating system at one time. |
alertsched |
An integer that specifies the interval, in seconds, at which to notify an administrator of a network event. |
erroralert |
An 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. |
logonalert |
An integer that specifies how many invalid logon attempts to allow a user before notifying an administrator. |
accessalert |
An integer that specifies the number of invalid attempts to access a file to allow before notifying an administrator. |
diskalert |
An 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. |
netioalert |
An integer that specifies, in tenths of a percent, the network I/O error ratio allowable before notifying an administrator. |
maxauditsz |
An integer that specifies, in kilobytes, the maximum size of the audit file. The audit file traces activity of the user. |
srvheuristics |
A string of flags that control operations on a server. |
auditedevents |
An integer that specifies the audit event control mask. |
autoprofile |
Controls the action of the server on the profile. May be either win32netcon.SW_AUTOPROF_LOAD_MASK or win32netcon.SW_AUTOPROF_SAVE_MASK. |
autopath |
A string containing the path for the profile. |
Attribute Name |
Description |
sessopens |
An integer that specifies the number of files that can be open in one session. |
sessvcs |
An integer that specifies the maximum number of virtual circuits per client. |
opensearch |
An integer that specifies the number of search operations that can be carried out simultaneously. |
sizreqbuf |
An integer that specifies the size, in bytes, of each server buffer. |
initworkitems |
An 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. |
maxworkitems |
An integer that specifies the maximum number of receive buffers, or work items, the server can allocate. |
rawworkitems |
An 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. |
irpstacksize |
An integer that specifies the number of stack locations in IRPs allocated by the server. |
maxrawbuflen |
An integer that specifies the maximum raw mode buffer size. |
sessusers |
An integer that specifies the maximum number of users that can be logged on to a server using a single virtual circuit. |
sessconns |
An integer that specifies the maximum number of tree connections that can be made on the server with one virtual circuit. |
maxpagedmemoryusage |
An 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. |
maxnonpagedmemoryusage |
An 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. |
enablesoftcompat |
An undocumented integer member. Please see the Win32 SDK for more details. |
enableforcedlogoff |
An 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. |
timesource |
An integer that specifies whether the server is a reliable time source. |
acceptdownlevelapis |
An integer that specifies whether the server will accept function calls from previous generation LAN Manager clients. |
lmannounce |
An integer that specifies the LAN Manager server announcement interval. |
Attribute Name |
Description |
sessopens |
An integer that specifies the number of files that can be open in one session. |
sessvcs |
An integer that specifies the maximum number of virtual circuits per client. |
opensearch |
An integer that specifies the number of search operations that can be carried out simultaneously. |
sizreqbuf |
An integer that specifies the size, in bytes, of each server buffer. |
initworkitems |
An 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. |
maxworkitems |
An integer that specifies the maximum number of receive buffers, or work items, the server can allocate. |
rawworkitems |
An 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. |
irpstacksize |
An integer that specifies the number of stack locations in IRPs allocated by the server. |
maxrawbuflen |
An integer that specifies the maximum raw mode buffer size. |
sessusers |
An integer that specifies the maximum number of users that can be logged on to a server using a single virtual circuit. |
sessconns |
An integer that specifies the maximum number of tree connections that can be made on the server using a single virtual circuit. |
maxpagedmemoryusage |
An 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. |
maxnonpagedmemoryusage |
An 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. |
enablesoftcompat |
An undocumented integer member. Please see the Win32 API documentation for more details. |
enableforcedlogoff |
An 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. |
timesource |
An integer that specifies whether the server is a reliable time source. |
acceptdownlevelapis |
An integer that specifies whether the server will accept function calls from previous generation LAN Manager clients. |
lmannounce |
An integer that specifies the LAN Manager server announcement interval. |
domain |
A string that specifies the name of the server’s domain. |
maxcopyreadlen |
An undocumented integer member. Please see the Win32 API documentation for more details. |
maxcopywritelen |
An undocumented integer member. Please see the Win32 API documentation for more details. |
minkeepsearch |
An undocumented integer member. Please see the Win32 API documentation for more details. |
maxkeepsearch |
An integer that specifies the length of time the server retains information about directory searches that have not ended. |
minkeepcomplsearch |
An undocumented integer member. Please see the Win32 API documentation for more details. |
maxkeepcomplsearch |
An undocumented integer member. Please see the Win32 API documentation for more details. |
threadcountadd |
An undocumented integer member. Please see the Win32 API documentation for more details. |
numblockthreads |
An undocumented integer member. Please see the Win32 API documentation for more details. |
scavtimeout |
An 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. |
minrcvqueue |
An 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. |
minfreeworkitems |
Specifies the minimum number of available receive work items needed for the server to begin processing a server message block. |
xactmemsize |
An integer that specifies the size of the shared memory region that processes server functions. |
threadpriority |
An 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. |
maxmpxct |
An 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. |
oplockbreakwait |
An integer that specifies the time to wait before timing out an opportunistic lock break request. |
oplockbreakresponsewait |
An integer that specifies the time to wait before timing out an opportunistic lock break request. |
enableoplocks |
An 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. |
enableoplockforceclose |
An undocumented integer member. Please see the Win32 API documentation for more details. |
enablefcbopens |
An 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. |
enableraw |
An 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. |
enablesharednetdrives |
An integer that specifies whether the server allows redirected server drives to be shared. |
minfreeconnections |
An 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. |
maxfreeconnections |
An 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. |
|
|
|
|
Attribute Name |
Description |
name |
A string containing the group name. |
Attribute Name |
Description |
name |
A string containing the group name. |
comment |
A string containing a comment for the group. |
Attribute Name |
Description |
name |
A string containing the group name. |
comment |
A string containing a comment for the group. |
group_id |
An integer value that contains the relative identifier of the global group. |
attributes |
An integer that holds the attributes for the group. |
Attribute Name |
Description |
comment |
A string containing a comment for the group. |
Attribute Name |
Description |
attributes |
An integer that holds the attributes for the group. |
|
|
|
|
Attribute Name |
Description |
name |
A string containing the group name. |
|
|
|
|
Attribute Name |
Description |
name |
A string containing the name of a local group to which the user belongs. |
|
|
|
|
Attribute Name |
Description |
name |
A string containing the local group name. |
Attribute Name |
Description |
name |
A string containing the local group name. |
comment |
A string containing a comment for the local group. |
Attribute Name |
Description |
comment |
A string containing a comment for the local group. |
|
|
|
|
Attribute Name |
Description |
sid |
A PySID object identifying the user. |
Attribute Name |
Description |
sid |
A PySID object identifying the user. |
sidusage |
Specifies the account type associated with the sid element. May be one of ntsecuritycon.SidTypeUser, ntsecuritycon.SidTypeGroup, ntsecuritycon.SidTypeWellKnownGroup, ntsecuritycon.SidTypeDeletedAccount, or ntsecuritycon.SidTypeUnknown. |
name |
The account name of the local group member identified by the sid. |
Attribute Name |
Description |
sid |
A PySID object identifying the user. |
sidusage |
Specifies the account type associated with the sid element. |
domainandname |
The domain and account name of the local group member identified by the sid. |
Attribute Name |
Description |
domainandname |
The domain and account name of the local group member identified by the sid. |