pywincffi.kernel32 package¶
Submodules¶
pywincffi.kernel32.comms module¶
Communications¶
A module containing Windows functions related to communications.
-
pywincffi.kernel32.comms.
ClearCommError
(hFile)[source]¶ Retrieves information about a communications error and reports the current status of a communications device.
Parameters: hFile (pywincffi.wintypes.HANDLE) – A handle to the communications device, typically created by CreateFile()
Return type: tuple Returns: Returns a two element tuple containing the lpErrors
andlpStat
result objects.lpErrors
- Contains the mast indicating the type of errorlpStat
- ACOMSTAT
structure which contains the device’s- information.
pywincffi.kernel32.console module¶
Console¶
A module containing functions for interacting with a Windows console.
-
pywincffi.kernel32.console.
CreateConsoleScreenBuffer
(dwDesiredAccess, dwShareMode, lpSecurityAttributes=None, dwFlags=None)[source]¶ Creates a console screen buffer.
Parameters: - dwDesiredAccess (int or None) – The access to the console screen buffer. If None is provided then the Windows APIs will use a default security descriptor.
- dwShareMode (int or None) – Controls the options for sharing the resulting handle. If None or 0 then the resulting buffer cannot be shared.
- lpSecurityAttributes (pywincffi.wintypes.SECURITY_ATTRIBUTES) – Extra security attributes that determine if the resulting handle can be inherited. If None is provided, which is the default, then the handle cannot be inherited.
- dwFlags (int) – The type of console buffer to create. The flag is superficial because
it only accepts None or
CONSOLE_TEXTMODE_BUFFER
as inputs. If no value is provided, which is the default, thenCONSOLE_TEXTMODE_BUFFER
is automatically used.
Return type: pywincffi.wintypes.HANDLE`
Returns: Returns the handle created by the underlying C function.
pywincffi.kernel32.CloseHandle()
should be called on the handle when you are done with it.
-
pywincffi.kernel32.console.
GetConsoleScreenBufferInfo
(hConsoleOutput)[source]¶ Retrieves information about the specified console screen buffer.
Parameters: hConsoleOutput (pywincffi.wintypes.HANDLE) – A handle to the console screen buffer. The handle must have the GENERIC_READ
access right.Returns: Returns a ffi data structure with attributes corresponding to the fields on the PCONSOLE_SCREEN_BUFFER_INFO
struct.
-
pywincffi.kernel32.console.
SetConsoleTextAttribute
(hConsoleOutput, wAttributes)[source]¶ Sets the attributes of characters written to a console buffer.
Parameters: - hConsoleOutput (pywincffi.wintypes.HANDLE) – A handle to the console screen buffer. The handle must have the
GENERIC_READ
access right. - wAttributes (int) – The character attribute(s) to set.
- hConsoleOutput (pywincffi.wintypes.HANDLE) – A handle to the console screen buffer. The handle must have the
pywincffi.kernel32.events module¶
Events¶
A module containing Windows functions for working with events.
-
pywincffi.kernel32.events.
CreateEvent
(lpEventAttributes=None, bManualReset=True, bInitialState=False, lpName=None)[source]¶ Creates or opens an named or unnamed event object.
- :keyword
pywincffi.wintypes.SECURITY_ATTRIBUTES
lpEventAttributes: - If not provided then, by default, the handle cannot be inherited by a subprocess.
Parameters: - bManualReset (bool) –
If True then this function will create a manual reset event which must be manually reset with
ResetEvent()
. Refer to the msdn documentation for full information.Default:
True
- bInitialState (bool) –
If True the initial state will be ‘signaled’.
Default:
False
- lpName (str) – Type is
unicode
on Python 2,str
on Python 3. The optional case-sensitive name of the event. If not provided then the event will be created without an explicit name.
Returns: Returns a
pywincffi.wintypes.HANDLE
to the event. If an event by the given name already exists then it will be returned instead of creating a new event.- :keyword
-
pywincffi.kernel32.events.
OpenEvent
(dwDesiredAccess, bInheritHandle, lpName)[source]¶ Opens an existing named event.
Parameters: Returns: Returns a
pywincffi.wintypes.HANDLE
to the event.
pywincffi.kernel32.file module¶
Files¶
A module containing common Windows file functions for working with files.
-
pywincffi.kernel32.file.
CreateFile
(lpFileName, dwDesiredAccess, dwShareMode=None, lpSecurityAttributes=None, dwCreationDisposition=None, dwFlagsAndAttributes=None, hTemplateFile=None)[source]¶ Creates or opens a file or other I/O device. Default values are provided for some of the default arguments for CreateFile() so its behavior is close to Pythons
open()
function.See also
https://msdn.microsoft.com/en-us/library/aa363858 https://msdn.microsoft.com/en-us/library/gg258116
Parameters: - lpFileName (str) – Type is
unicode
on Python 2,str
on Python 3. The path to the file or device being created or opened. - dwDesiredAccess (int) – The requested access to the file or device. Microsoft’s documentation has extensive notes on this parameter in the seealso links above.
- dwShareMode (int) – Access and sharing rights to the handle being created. If not provided
with an explicit value,
FILE_SHARE_READ
will be used which will other open operations or process to continue to read from the file. - lpSecurityAttributes (pywincffi.wintypes.SECURITY_ATTRIBUTES) – See Microsoft’s documentation for more detailed information.
- dwCreationDisposition (int) – Action to take when the file or device does not exist. If not
provided with an explicit value,
CREATE_ALWAYS
will be used which means existing files will be overwritten. - dwFlagsAndAttributes (int) – The file or device attributes and flags. If not provided an explict
value,
FILE_ATTRIBUTE_NORMAL
will be used giving the handle essentially no special attributes. - hTemplateFile (pywincffi.wintypes.HANDLE) – A handle to a template file with the
GENERIC_READ
access right. See Microsoft’s documentation for more information. If not provided an explicit value,NULL
will be used instead.
Returns: The file
pywincffi.wintypes.HANDLE
created byCreateFile
.- lpFileName (str) – Type is
-
pywincffi.kernel32.file.
FlushFileBuffers
(hFile)[source]¶ Flushes the buffer of the specified file to disk.
Parameters: hFile (pywincffi.wintypes.HANDLE) – The handle to flush to disk.
-
pywincffi.kernel32.file.
GetTempPath
()[source]¶ Retrieves the path of the directory designated for temporary files.
Returns: Returns a string containing the value produced by the underlying C function.
-
pywincffi.kernel32.file.
LockFileEx
(hFile, dwFlags, nNumberOfBytesToLockLow, nNumberOfBytesToLockHigh, lpOverlapped=None)[source]¶ Locks
hFile
for exclusive access by the calling process.Parameters: - hFile (pywincffi.wintypes.HANDLE) – The handle to the file to lock. This handle must have been
created with either the
GENERIC_READ
orGENERIC_WRITE
right. - dwFlags (int) –
One or more of the following flags:
LOCKFILE_EXCLUSIVE_LOCK
- Request an exclusive lock.LOCKFILE_FAIL_IMMEDIATELY
- Return immediately if the lock could not be acquired. OtherwiseLockFileEx()
will wait.
- nNumberOfBytesToLockLow (int) – The start of the byte range to lock.
- nNumberOfBytesToLockHigh (int) – The end of the byte range to lock.
- lpOverlapped (pywincffi.wintypes.OVERLAPPED) – The underlying Windows API requires lpOverlapped, which acts both an input argument and may contain results after calling. If None is provided, a throw-away zero-filled instance will be created to support such call. See Microsoft’s documentation for intended usage.
- hFile (pywincffi.wintypes.HANDLE) – The handle to the file to lock. This handle must have been
created with either the
-
pywincffi.kernel32.file.
MoveFileEx
(lpExistingFileName, lpNewFileName, dwFlags=None)[source]¶ Moves an existing file or directory, including its children, see the MSDN documentation for full options.
Parameters: - lpExistingFileName (str) – Type is
unicode
on Python 2,str
on Python 3. Name of the file or directory to perform the operation on. - lpNewFileName (str) – Type is
unicode
on Python 2,str
on Python 3. Optional new name of the path or directory. This value may beNone
. - dwFlags (int) – Parameters which control the operation of
MoveFileEx()
. See the MSDN documentation for full details. By defaultMOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH
is used.
- lpExistingFileName (str) – Type is
-
pywincffi.kernel32.file.
ReadFile
(hFile, nNumberOfBytesToRead, lpOverlapped=None)[source]¶ Read the specified number of bytes from
hFile
.Parameters: - hFile (pywincffi.wintypes.HANDLE) – The handle to read from.
- nNumberOfBytesToRead (int) – The number of bytes to read from
hFile
- lpOverlapped (pywincffi.wintypes.OVERLAPPED) –
See Microsoft’s documentation for intended usage and below for an example.
>>> from pywincffi.core import dist >>> from pywincffi.kernel32 import ReadFile, CreateEvent >>> from pywincffi.wintypes import OVERLAPPED >>> hEvent = CreateEvent(...) >>> lpOverlapped = OVERLAPPED() >>> lpOverlapped.hEvent = hEvent >>> read_data = ReadFile( # read 12 bytes from hFile ... hFile, 12, lpOverlapped=lpOverlapped)
Returns: Returns the binary data read from
hFile
Type isstr
on Python 2,bytes
on Python 3.
-
pywincffi.kernel32.file.
UnlockFileEx
(hFile, nNumberOfBytesToUnlockLow, nNumberOfBytesToUnlockHigh, lpOverlapped=None)[source]¶ Unlocks a region in the specified file.
Parameters: - hFile (pywincffi.wintypes.HANDLE) – The handle to the file to unlock. This handle must have been
created with either the
GENERIC_READ
orGENERIC_WRITE
right. - nNumberOfBytesToUnlockLow (int) – The start of the byte range to unlock.
- nNumberOfBytesToUnlockHigh (int) – The end of the byte range to unlock.
- lpOverlapped (pywincffi.wintypes.OVERLAPPED) – The underlying Windows API requires lpOverlapped, which acts both an input argument and may contain results after calling. If None is provided, a throw-away zero-filled instance will be created to support such call. See Microsoft’s documentation for intended usage.
- hFile (pywincffi.wintypes.HANDLE) – The handle to the file to unlock. This handle must have been
created with either the
-
pywincffi.kernel32.file.
WriteFile
(hFile, lpBuffer, nNumberOfBytesToWrite=None, lpOverlapped=None)[source]¶ Writes data to
hFile
which may be an I/O device for file.Parameters: - hFile (pywincffi.wintypes.HANDLE) – The handle to write to.
- lpBuffer (str/bytes) – Type is
str
on Python 2,bytes
on Python 3. The data to be written to the file or device. - nNumberOfBytesToWrite (int) – The number of bytes to be written. Defaults to len(lpBuffer).
- lpOverlapped (pywincffi.wintypes.OVERLAPPED) –
See Microsoft’s documentation for intended usage and below for an example.
>>> from pywincffi.core import dist >>> from pywincffi.kernel32 import WriteFile, CreateEvent >>> from pywincffi.wintypes import OVERLAPPED >>> hEvent = CreateEvent(...) >>> lpOverlapped = OVERLAPPED() >>> lpOverlapped.hEvent = hEvent >>> bytes_written = WriteFile( ... hFile, "Hello world", lpOverlapped=lpOverlapped)
Returns: Returns the number of bytes written.
pywincffi.kernel32.handle module¶
Handles¶
A module containing general functions for working with handle
objects. The functions provided here are part of the kernel32
library.
-
pywincffi.kernel32.handle.
CloseHandle
(hObject)[source]¶ Closes an open object handle.
Parameters: hObject (pywincffi.wintypes.HANDLE or pywincffi.wintypes.SOCKET) – The handle object to close.
-
pywincffi.kernel32.handle.
DuplicateHandle
(hSourceProcessHandle, hSourceHandle, hTargetProcessHandle, dwDesiredAccess, bInheritHandle, dwOptions)[source]¶ Duplicates an object handle.
Parameters: - hSourceProcessHandle (pywincffi.wintypes.HANDLE) – A handle to the process which owns the handle to be duplicated.
- hSourceHandle (pywincffi.wintypes.HANDLE) – The handle to be duplicated.
- hTargetProcessHandle (pywincffi.wintypes.HANDLE) – A handle to the process which should receive the duplicated handle.
- dwDesiredAccess (int) – The access requested for the new handle.
- bInheritHandle (bool) – True if the handle should be inheritable by new processes.
- dwOptions (int) –
Options which control how the handle is duplicated. Valid values are any of the below (or a combination of):
DUPLICATE_CLOSE_SOURCE
- Closes the source handle, even- if there’s an error.
DUPLICATE_SAME_ACCESS
- Ignores thedwDesiredAccess
- parameter duplicates with the same access as the original handle.
Return type: pywincffi.wintypes.HANDLE
Returns: Returns the duplicated handle.
-
pywincffi.kernel32.handle.
GetHandleInformation
(hObject)[source]¶ Returns properties of an object handle.
Parameters: hObject (pywincffi.wintypes.HANDLE) – A handle to an object whose information is to be retrieved. Return type: int Returns: Returns the set of bit flags that specify properties of hObject
.
-
pywincffi.kernel32.handle.
GetStdHandle
(nStdHandle)[source]¶ Retrieves a handle to the specified standard device (standard input, standard output, or standard error).
Parameters: nStdHandle (int) – The standard device to retrieve. Return type: pywincffi.wintypes.HANDLE Returns: Returns a handle to the standard device retrieved.
pywincffi.kernel32.overlapped module¶
Overlapped¶
A module containing Windows functions for working with OVERLAPPED objects.
-
pywincffi.kernel32.overlapped.
GetOverlappedResult
(hFile, lpOverlapped, bWait)[source]¶ Retrieves the results of an overlapped operation on the specified file, named pipe, or communications device. To specify a timeout interval or wait on an alertable thread, use GetOverlappedResultEx.
Parameters: - hFile (pywincffi.wintypes.HANDLE) – A handle to the file, named pipe, or communications device. This is the same handle that was specified when the overlapped operation was started by a call to the ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl, or WaitCommEvent function.
- lpOverlapped (pywincffi.wintypes.OVERLAPPED) – The an OVERLAPPED object that was specified when the overlapped operation was started
- bWait (bool) – If this parameter is TRUE, and the Internal member of the lpOverlapped structure is STATUS_PENDING, the function does not return until the operation has been completed. If this parameter is FALSE and the operation is still pending, the function returns FALSE and the GetLastError function returns ERROR_IO_INCOMPLETE
Returns: The number of bytes that were actually transferred by a read or write operation. For a TransactNamedPipe operation, this is the number of bytes that were read from the pipe. For a DeviceIoControl operation, this is the number of bytes of output data returned by the device driver. For a ConnectNamedPipe or WaitCommEvent operation, this value is undefined.
pywincffi.kernel32.pipe module¶
Pipe¶
A module for working with pipe objects in Windows.
-
pywincffi.kernel32.pipe.
CreatePipe
(lpPipeAttributes=None, nSize=0)[source]¶ Creates an anonymous pipe and returns the read and write handles.
See also
https://msdn.microsoft.com/en-us/library/aa365152 https://msdn.microsoft.com/en-us/library/aa379560
>>> from pywincffi.core import dist >>> from pywincffi.kernel32 import CreatePipe >>> from pywincffi.wintypes import SECURITY_ATTRIBUTES >>> lpPipeAttributes = SECURITY_ATTRIBUTES() >>> lpPipeAttributes.bInheritHandle = True >>> reader, writer = CreatePipe(lpPipeAttributes=lpPipeAttributes)
Parameters: - lpPipeAttributes (pywincffi.wintypes.SECURITY_ATTRIBUTES) – The security attributes to apply to the handle. By default
NULL
will be passed in, meaning the handle we create cannot be inherited. For more detailed information see the links below. - nSize (int) – The size of the buffer in bytes. Passing in 0, which is the default will cause the system to use the default buffer size.
Returns: Returns a tuple of
pywincffi.wintype.HANDLE
containing the reader and writer ends of the pipe that was created. The user of this function is responsible for calling CloseHandle at some point.- lpPipeAttributes (pywincffi.wintypes.SECURITY_ATTRIBUTES) – The security attributes to apply to the handle. By default
-
pywincffi.kernel32.pipe.
PeekNamedPipe
(hNamedPipe, nBufferSize)[source]¶ Copies data from a pipe into a buffer without removing it from the pipe.
Parameters: - hNamedPipe (pywincffi.wintypes.HANDLE) – The handele to the pipe object we want to peek into.
- nBufferSize (int) – The number of bytes to ‘peek’ into the pipe.
Return type: Returns: Returns an instance of
PeekNamedPipeResult
which contains the buffer read, number of bytes read and the result.
-
class
pywincffi.kernel32.pipe.
PeekNamedPipeResult
(lpBuffer, lpBytesRead, lpTotalBytesAvail, lpBytesLeftThisMessage)¶ Bases:
tuple
-
lpBuffer
¶ Alias for field number 0
-
lpBytesLeftThisMessage
¶ Alias for field number 3
-
lpBytesRead
¶ Alias for field number 1
-
lpTotalBytesAvail
¶ Alias for field number 2
-
-
pywincffi.kernel32.pipe.
SetNamedPipeHandleState
(hNamedPipe, lpMode=None, lpMaxCollectionCount=None, lpCollectDataTimeout=None)[source]¶ Sets the read and blocking mode of the specified
hNamedPipe
.Parameters: - hNamedPipe (pywincffi.wintypes.HANDLE) – A handle to the named pipe instance.
- lpMode (int) –
The new pipe mode which is a combination of read mode:
PIPE_READMODE_BYTE
PIPE_READMODE_MESSAGE
And a wait-mode flag:
PIPE_WAIT
PIPE_NOWAIT
- lpMaxCollectionCount (int) – The maximum number of bytes collected.
- lpCollectDataTimeout (int) – The maximum time, in milliseconds, that can pass before a remote named pipe transfers information
pywincffi.kernel32.process module¶
Process¶
Provides functions, constants and utilities that wrap the Windows functions associated with process management and interaction. This module also provides several constants as well, see Microsoft’s documentation for the constant names and their purpose:
- Process Security and Access Rights - https://msdn.microsoft.com/en-us/library/windows/desktop/ms684880
Note
Not all constants may be defined
-
pywincffi.kernel32.process.
CreateProcess
(lpApplicationName=None, lpCommandLine=None, lpProcessAttributes=None, lpThreadAttributes=None, bInheritHandles=True, dwCreationFlags=None, lpEnvironment=None, lpCurrentDirectory=None, lpStartupInfo=None)[source]¶ Creates a new process and its primary thread. The process will be created in the same security context as the original process.
Parameters: - lpStartupInfo (pywincffi.wintypes.STARTUPINFO) –
See Microsoft’s documentation for additional information.
Warning
The STARTUPINFOEX structure is not currently supported for this input.
- lpCommandLine (str) – The command line to be executed. The maximum length of this parameter
is 32768. If no value is provided for
lpApplicationName
then the module name portion oflpCommandLine
cannot exceedMAX_PATH
. - lpApplicationName (str) – The name of the module or application to be executed. This can be
either the fully qualified path name or a partial name. The system
path will not be searched. If no value is provided for this keyword
then the input to
lpCommandLine
will be used by Windows instead. - lpProcessAttributes (pywincffi.wintypes.SECUREITY_ATTRIBUTES) – Determines whether the returned handle to the new process object can be inherited by child processes. By default, the handle cannot be inherited.
- lpThreadAttributes (pywincffi.wintypes.SECUREITY_ATTRIBUTES) – Determines if the returned handle to the new thread object can be inherited by child processes. By default, the thread cannot be inherited.
- bInheritHandles (bool) – If True (the default) the handles inherited by the calling process are inherited by the new process.
- dwCreationFlags (int) – Controls the priority class and creation of the process. By default
the process will flag will default to
NORMAL_PRIORITY_CLASS | CREATE_UNICODE_ENVIRONMENT
- lpEnvironment (dict) –
The environment for the new process. By default the the process will be created with the same environment as the parent process.
Note
All keys and values in the environment must be either unicode (Python 2) or strings (Python 3).
Note
This keyword will completely override the current if you wish to update the current environment instead then you will need to make and update a copy.
Warning
Excluding certain system environment variables such as
PATH
orSYSTEMROOT
may result in crashes or unexpected behaviors depending on the program being run. - lpCurrentDirectory (str) –
- The full path to the current directory for the process. If not
- provided then the process will have the same working directory as the parent process.
Raises: InputError – Raised if
lpCommandLine
is too long or there are other input problems.Return type: Returns: Returns a named tuple containing
lpCommandLine
andlpProcessInformation
. ThelpProcessInformation
will be an instance ofpywincffi.wintypes.structures.PROCESS_INFORMATION
- lpStartupInfo (pywincffi.wintypes.STARTUPINFO) –
-
class
pywincffi.kernel32.process.
CreateProcessResult
(lpCommandLine, lpProcessInformation)¶ Bases:
tuple
-
lpCommandLine
¶ Alias for field number 0
-
lpProcessInformation
¶ Alias for field number 1
-
-
pywincffi.kernel32.process.
CreateToolhelp32Snapshot
(dwFlags, th32ProcessID)[source]¶ Takes a snapshot of the specified processes, as well as the heaps, modules, and threads used by these processes.
Parameters: Return type: pywincffi.wintypes.HANDLE
Returns: If the function succeeds, it returns an open handle to the specified snapshot.
-
pywincffi.kernel32.process.
GetCurrentProcess
()[source]¶ Returns a handle to the current thread.
Note
Calling
pywincffi.kernel32.handle.CloseHandle()
on the handle produced by this function will produce an exception.Returns: The pywincffi.wintypes.HANDLE
to the current process.
-
pywincffi.kernel32.process.
GetExitCodeProcess
(hProcess)[source]¶ Retrieves the exit code of the given process handle. To retrieve a process handle use
OpenProcess()
.Warning
You may want to use
process_exit_code()
instead of this function if you’re just checking to see if a process has exited at all.Parameters: hProcess (pywincffi.wintypes.HANDLE) – The handle of the process to retrieve the exit code for. Returns: Returns the exit code of the requested process if one can be found.
-
pywincffi.kernel32.process.
GetProcessId
(Process)[source]¶ Returns the pid of the process handle provided in
Process
.Parameters: Process (pywincffi.wintypes.HANDLE) – The handle of the process. Returns: Returns an integer which represents the pid of the given process handle.
-
pywincffi.kernel32.process.
OpenProcess
(dwDesiredAccess, bInheritHandle, dwProcessId)[source]¶ Opens an existing local process object.
Parameters: Returns: Returns a
pywincffi.wintypes.HANDLE
to the opened process. This value can be used by other functions such asTerminateProcess()
.
-
pywincffi.kernel32.process.
TerminateProcess
(hProcess, uExitCode)[source]¶ Terminates the specified process and all of its threads.
Parameters: - hProcess (pywincffi.wintypes.HANDLE) – A handle to the process to be terminated.
- uExitCode (int) – The exit code of the processes and threads as a result of calling this function.
-
pywincffi.kernel32.process.
module_name
(path)[source]¶ Returns the module name for the given
path
>>> module_name(u"C:\Python27\python.exe -c 'print True'") 'C:\Python27\python.exe' >>> module_name(u"C:\Program Files (x86)\Foo\program.exe -h") 'C:\Program' >>> module_name(u"'C:\Program Files (x86)\Foo\program.exe' -h") 'C:\Program Files (x86)\Foo\program.exe'
This function is used internally by
CreateProcess()
to assist in validating input to thelpCommandLine
argument. When callingCreateProcess()
iflpApplicationName
is not set thenlpCommandLine
’s module name cannot exceedMAX_PATH
.Raises: TypeError – Raised if path
is not a text type.