"""
Handles
-------
A module containing general functions for working with handle
objects. The functions provided here are part of the ``kernel32`` library.
"""
from six import integer_types
from pywincffi.core import dist
from pywincffi.core.checks import NON_ZERO, input_check, error_check
from pywincffi.exceptions import WindowsAPIError
from pywincffi.wintypes import HANDLE, SOCKET, wintype_to_cdata
[docs]def GetStdHandle(nStdHandle):
"""
Retrieves a handle to the specified standard
device (standard input, standard output, or standard error).
.. seealso::
https://msdn.microsoft.com/en-us/library/ms683231
:param int nStdHandle:
The standard device to retrieve.
:rtype: pywincffi.wintypes.HANDLE
:return:
Returns a handle to the standard device retrieved.
"""
_, library = dist.load()
input_check("nStdHandle", nStdHandle,
allowed_values=(library.STD_INPUT_HANDLE,
library.STD_OUTPUT_HANDLE,
library.STD_ERROR_HANDLE))
handle = library.GetStdHandle(nStdHandle)
if handle == library.INVALID_HANDLE_VALUE: # pragma: no cover
raise WindowsAPIError(
"GetStdHandle", "Invalid Handle", library.INVALID_HANDLE_VALUE,
expected_return_code="not %r" % library.INVALID_HANDLE_VALUE)
return HANDLE(handle)
[docs]def CloseHandle(hObject):
"""
Closes an open object handle.
.. seealso::
https://msdn.microsoft.com/en-us/library/ms724211
:type hObject: pywincffi.wintypes.HANDLE or pywincffi.wintypes.SOCKET
:param hObject:
The handle object to close.
"""
input_check("hObject", hObject, (HANDLE, SOCKET))
_, library = dist.load()
code = library.CloseHandle(wintype_to_cdata(hObject))
error_check("CloseHandle", code=code, expected=NON_ZERO)
[docs]def DuplicateHandle( # pylint: disable=too-many-arguments
hSourceProcessHandle, hSourceHandle, hTargetProcessHandle,
dwDesiredAccess, bInheritHandle, dwOptions):
"""
Duplicates an object handle.
.. seealso::
https://msdn.microsoft.com/en-us/ms724251
:param pywincffi.wintypes.HANDLE hSourceProcessHandle:
A handle to the process which owns the handle to be duplicated.
:param pywincffi.wintypes.HANDLE hSourceHandle:
The handle to be duplicated.
:param pywincffi.wintypes.HANDLE hTargetProcessHandle:
A handle to the process which should receive the duplicated handle.
:param int dwDesiredAccess:
The access requested for the new handle.
:param bool bInheritHandle:
True if the handle should be inheritable by new processes.
:param int dwOptions:
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 the ``dwDesiredAccess``
parameter duplicates with the same access as the original
handle.
:rtype: pywincffi.wintypes.HANDLE
:return:
Returns the duplicated handle.
"""
ffi, library = dist.load()
input_check("hSourceProcessHandle", hSourceProcessHandle, HANDLE)
input_check("hSourceHandle", hSourceHandle, HANDLE)
input_check("hTargetProcessHandle", hTargetProcessHandle, HANDLE)
input_check("dwDesiredAccess", dwDesiredAccess, integer_types)
input_check("bInheritHandle", bInheritHandle, bool)
input_check("dwOptions", dwOptions, allowed_values=(
library.DUPLICATE_CLOSE_SOURCE, library.DUPLICATE_SAME_ACCESS,
library.DUPLICATE_CLOSE_SOURCE | library.DUPLICATE_SAME_ACCESS
))
lpTargetHandle = ffi.new("LPHANDLE")
code = library.DuplicateHandle(
wintype_to_cdata(hSourceProcessHandle),
wintype_to_cdata(hSourceHandle),
wintype_to_cdata(hTargetProcessHandle),
lpTargetHandle,
ffi.cast("DWORD", dwDesiredAccess),
ffi.cast("BOOL", bInheritHandle),
ffi.cast("DWORD", dwOptions)
)
error_check("DuplicateHandle", code, expected=NON_ZERO)
return HANDLE(lpTargetHandle[0])