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.events module¶
Events¶
A module containing Windows functions for working with events.
-
pywincffi.kernel32.events.
CreateEvent
(bManualReset, bInitialState, lpEventAttributes=None, lpName=None)[source]¶ Creates or opens an named or unnamed event object.
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. - bInitialState (bool) – If True the initial state will be ‘signaled’.
- :keyword
pywincffi.wintypes.SECURITY_ATTRIBUTES
lpEventAttributes: - If not provided then, by default, the handle cannot be inherited by a subprocess.
Parameters: 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.- bManualReset (bool) – If True then this function will create a manual reset
event which must be manually reset with
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.
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) – 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.pipe module¶
Pipe¶
A module for working with pipe objects in Windows.
-
pywincffi.kernel32.pipe.
CreatePipe
(nSize=0, lpPipeAttributes=None)[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: - 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.
- 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.
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.
-
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.
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.