pywincffi.kernel32 package

Submodules

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) – 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 (struct) – A pointer to a SECURITY_ATTRIBUTES structure, see Microsoft’s documentation for more detailed information. If not provided with an explicit value, NULL will be used instead which will mean the handle can’t be inherited by any child process.
  • 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 (handle) – A value 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:

Returns the file handle created by CreateFile.
pywincffi.kernel32.file.FlushFileBuffers(hFile)[source]

Flushes the buffer of the specified file to disk.

See also

https://msdn.microsoft.com/en-us/library/aa364439

Parameters:hFile (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.

See also

https://msdn.microsoft.com/en-us/library/aa365203

Parameters:
  • hFile (handle) – The handle to the file to lock. This handle must have been created with either the GENERIC_READ or GENERIC_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. Otherwise LockFileEx() will wait.
  • nNumberOfBytesToLockLow (int) – The start of the byte range to lock.
  • nNumberOfBytesToLockHigh (int) – The end of the byte range to lock.
  • lpOverlapped (LPOVERLAPPED) – A pointer to an OVERLAPPED structure. If not provided one will be constructed for you.
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.

See also

https://msdn.microsoft.com/en-us/library/aa365240

Parameters:
  • lpExistingFileName (str) – Name of the file or directory to perform the operation on.
  • lpNewFileName (str) – Optional new name of the path or directory. This value may be None.
  • dwFlags (int) – Parameters which control the operation of MoveFileEx(). See the MSDN documentation for full details. By default MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH is used.
pywincffi.kernel32.file.ReadFile(hFile, nNumberOfBytesToRead, lpOverlapped=None)[source]

Read the specified number of bytes from hFile.

See also

https://msdn.microsoft.com/en-us/library/aa365467

Parameters:
  • hFile (handle) – The handle to read from
  • nNumberOfBytesToRead (int) – The number of bytes to read from hFile
  • lpOverlapped (None or OVERLAPPED) –

    None or a pointer to a OVERLAPPED structure. See Microsoft’s documentation for intended usage and below for an example of this struct.

    >>> from pywincffi.core import dist
>>> ffi, library = dist.load()
>>> hFile = None # normally, this would be a handle
>>> lpOverlapped = ffi.new(
...     "OVERLAPPED[1]", [{
...         "hEvent": hFile
...     }]
... )
>>> read_data = ReadFile(  # read 12 bytes from hFile
...     hFile, 12, lpOverlapped=lpOverlapped)
Returns:

Returns the data read from hFile
pywincffi.kernel32.file.UnlockFileEx(hFile, nNumberOfBytesToUnlockLow, nNumberOfBytesToUnlockHigh, lpOverlapped=None)[source]

Unlocks a region in the specified file.

See also

https://msdn.microsoft.com/en-us/library/aa365716

Parameters:
  • hFile (handle) – The handle to the file to unlock. This handle must have been created with either the GENERIC_READ or GENERIC_WRITE right.
  • nNumberOfBytesToUnlockLow (int) – The start of the byte range to unlock.
  • nNumberOfBytesToUnlockHigh (int) – The end of the byte range to unlock.
  • lpOverlapped (LPOVERLAPPED) – A pointer to an OVERLAPPED structure. If not provided one will be constructed for you.
pywincffi.kernel32.file.WriteFile(hFile, lpBuffer, nNumberOfBytesToWrite=None, lpOverlapped=None, lpBufferType='wchar_t[]')[source]

Writes data to hFile which may be an I/O device for file.

See also

https://msdn.microsoft.com/en-us/library/aa365747

Parameters:
  • hFile (handle) – The handle to write to
  • lpBuffer (bytes, string or unicode.) – The data to be written to the file or device. We should be able to convert this value to unicode.
  • nNumberOfBytesToWrite (int) – The number of bytes to be written. By default this will be determinted based on the size of lpBuffer
  • lpOverlapped (None or OVERLAPPED) –

    None or a pointer to a OVERLAPPED structure. See Microsoft’s documentation for intended usage and below for an example of this struct.

    >>> from pywincffi.core import dist
>>> from pywincffi.kernel32 import WriteFile
>>> ffi, library = dist.load()
>>> hFile = None # normally, this would be a handle
>>> lpOverlapped = ffi.new(
...     "OVERLAPPED[1]", [{
...         "hEvent": hFile
...     }]
... )
>>> bytes_written = WriteFile(
...     hFile, "Hello world", lpOverlapped=lpOverlapped)
  • lpBufferType (str) – The type which should be passed to ffi.new(). If the data you’re passing into this function is a string and you’re using Python 2 for example you might use char[] here instead.
Returns:

Returns the number of bytes written

pywincffi.kernel32.handle module

Handles

A module containing general functions for working with handle objects.

pywincffi.kernel32.handle.CloseHandle(hObject)[source]

Closes an open object handle.

See also

https://msdn.microsoft.com/en-us/library/ms724211

Parameters:hObject (handle) – The handle object to close.
pywincffi.kernel32.handle.GetHandleInformation(hObject)[source]

Returns properties of an object handle.

See also

https://msdn.microsoft.com/en-us/library/ms724329

Parameters:hObject (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).

See also

https://msdn.microsoft.com/en-us/library/ms683231

Parameters:nStdHandle (int) – The standard device to retrieve
Return type:handle
Returns:Returns a handle to the standard device retrieved.
pywincffi.kernel32.handle.SetHandleInformation(hObject, dwMask, dwFlags)[source]

Sets properties of an object handle.

See also

https://msdn.microsoft.com/en-us/ms724935

Parameters:
  • hObject (handle) – A handle to an object whose information is to be set.
  • dwMask (int) – A mask that specifies the bit flags to be changed.
  • dwFlags (int) – Set of bit flags that specifies properties of hObject.
pywincffi.kernel32.handle.WaitForSingleObject(hHandle, dwMilliseconds)[source]

Waits for the specified object to be in a signaled state or for dwMiliseconds to elapse.

See also

https://msdn.microsoft.com/en-us/library/ms687032

Parameters:
  • hHandle (handle) – The handle to wait on.
  • dwMilliseconds (int) – The time-out interval.
pywincffi.kernel32.handle.handle_from_file(python_file)[source]

Given a standard Python file object produce a Windows handle object that be be used in Windows function calls.

Parameters:python_file (file) – The Python file object to convert to a Windows handle.
Returns:Returns a Windows handle object which is pointing at the provided python_file object.

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
>>> ffi, library = dist.load()
>>> lpPipeAttributes = ffi.new(
...     "SECURITY_ATTRIBUTES[1]", [{
...     "nLength": ffi.sizeof("SECURITY_ATTRIBUTES"),
...     "bInheritHandle": True,
...     "lpSecurityDescriptor": ffi.NULL
...     }]
... )
>>> 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 – The security attributes to apply to the handle. By default NULL will be passed in meaning then handle we create cannot be inherited. For more detailed information see the links below.
Returns:

Returns a tuple of handles 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.

See also

https://msdn.microsoft.com/en-us/library/aa365779

Parameters:
  • hNamedPipe (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:

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

See also

https://msdn.microsoft.com/en-us/library/aa365787

Parameters:
  • hNamedPipe (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:

Note

Not all constants may be defined

pywincffi.kernel32.process.GetCurrentProcess()[source]

Returns a handle to the current thread.

See also

https://msdn.microsoft.com/en-us/library/ms683179

Note

Calling pywincffi.kernel32.handle.CloseHandle() on the handle produced by this function will produce an exception.

Returns:The 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.

See also

https://msdn.microsoft.com/en-us/library/ms683189

Parameters:hProcess (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.

See also

https://msdn.microsoft.com/en-us/library/ms683215

Parameters:Process (handle) – The handle of the process to re
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.

See also

https://msdn.microsoft.com/en-us/library/ms684320

Parameters:
  • dwDesiredAccess (int) – The required access to the process object.
  • bInheritHandle (bool) – Enables or disable handle inheritance for child processes.
  • dwProcessId (int) – The id of the local process to be opened.
Returns:

Returns a handle to the opened process in the form of a void pointer. This value can be used by other functions such as TerminateProcess()
pywincffi.kernel32.process.pid_exists(pid, wait=0)[source]

Returns True if there’s a process associated with pid.

Parameters:
  • pid (int) – The id of the process to check for.
  • wait (int) – An optional keyword that controls how long we tell WaitForSingleObject() to wait on the process.
Raises:

ValidationError – Raised if there’s a problem with the value provided for pid.

Module contents

Kernel32 Sub-Package

Provides functions, constants and utilities that wrap functions provided by kernel32.dll.