Implement ClearCommError

docs/source/changelog.rst

@@ -22,6 +22,7 @@ Notable enhancements and changes are:
         * :issue:`75` - :func:`pywincffi.kernel32.events.ResetEvent`
         * :issue:`76` - :func:`pywincffi.kernel32.process.TerminateProcess`
         * :issue:`78` - :func:`pywincffi.kernel32.handle.DuplicateHandle`
+        * :issue:`79` - :func:`pywincffi.kernel32.process.ClearCommError`
 
 0.2.0
 ~~~~~

pywincffi/core/cdefs/headers/constants.h

@@ -186,6 +186,19 @@
 #define STARTF_USESIZE ...
 #define STARTF_USESTDHANDLES ...
 
+// ClearCommError
+#define CE_BREAK ...
+#define CE_FRAME ...
+#define CE_OVERRUN ...
+#define CE_RXOVER ...
+#define CE_RXPARITY ...
+#define CE_DNS ...
+#define CE_IOE ...
+#define CE_MODE ...
+#define CE_OOP ...
+#define CE_PTO ...
+#define CE_TXFULL ...
+
 // For the moment, we can't define this here.  When cffi
 // parses the header this returns -1 and cffi seems to
 // only handle positive integers right now.

pywincffi/core/cdefs/headers/functions.h

@@ -42,3 +42,6 @@ BOOL DuplicateHandle(HANDLE, HANDLE, HANDLE, LPHANDLE, DWORD, BOOL, DWORD);
 HANDLE CreateEvent(LPSECURITY_ATTRIBUTES, BOOL, BOOL, LPCTSTR);
 HANDLE OpenEvent(DWORD, BOOL, LPCTSTR);
 BOOL ResetEvent(HANDLE);
+
+// Communications
+BOOL ClearCommError(HANDLE, LPDWORD, LPCOMSTAT);

pywincffi/core/cdefs/headers/structs.h

@@ -67,3 +67,17 @@ typedef struct _STARTUPINFO {
   HANDLE hStdOutput;
   HANDLE hStdError;
 } STARTUPINFO, *LPSTARTUPINFO;
+
+// https://msdn.microsoft.com/en-us/library/aa363200
+typedef struct _COMSTAT {
+  DWORD fCtsHold  :1;
+  DWORD fDsrHold  :1;
+  DWORD fRlsdHold  :1;
+  DWORD fXoffHold  :1;
+  DWORD fXoffSent  :1;
+  DWORD fEof  :1;
+  DWORD fTxim  :1;
+  DWORD fReserved  :25;
+  DWORD cbInQue;
+  DWORD cbOutQue;
+} COMSTAT, *LPCOMSTAT;

pywincffi/kernel32/__init__.py

@@ -21,3 +21,4 @@
     GetProcessId, GetCurrentProcess, OpenProcess, GetExitCodeProcess,
     pid_exists, TerminateProcess)
 from pywincffi.kernel32.events import CreateEvent, OpenEvent, ResetEvent
+from pywincffi.kernel32.comms import ClearCommError

pywincffi/kernel32/comms.py

@@ -0,0 +1,42 @@
+"""
+Communications
+--------------
+
+A module containing Windows functions related to communications.
+"""
+
+from pywincffi.core import dist
+from pywincffi.core.checks import Enums, input_check, error_check
+
+
+def ClearCommError(hFile):
+    """
+    REtrieves information about a communications error and reports the
+    current status of a communications device.
+
+    .. seealso::
+
+        https://msdn.microsoft.com/en-us/aa363180
+
+    :param handle hFile:
+        A handle to the communications device, typically created by
+        :func:`CreateFile`
+
+    :rtype: tuple
+    :return:
+        Returns a two element tuple containing the ``lpErrors`` and
+        ``lpStat`` result objects.
+
+            * ``lpErrors`` - Contains the mast indicating the type of error
+            * ``lpStat`` - A ``COMSTAT`` structure which contains the device's
+               information.
+    """
+    input_check("hFile", hFile, Enums.HANDLE)
+
+    ffi, library = dist.load()
+
+    lpErrors = ffi.new("LPDWORD")
+    lpStat = ffi.new("LPCOMSTAT")
+    code = library.ClearCommError(hFile, lpErrors, lpStat)
+    error_check("ClearCommError", code=code, expected=Enums.NON_ZERO)
+    return lpErrors, lpStat

tests/test_kernel32/test_comms.py

@@ -0,0 +1,33 @@
+from pywincffi.core import dist
+from pywincffi.dev.testutil import TestCase
+from pywincffi.kernel32 import CreateFile, ClearCommError, CloseHandle
+from pywincffi.exceptions import WindowsAPIError
+
+
+class TestClearCommError(TestCase):
+    def test_clear_error(self):
+        ffi, library = dist.load()
+
+        # Try to find a COM device, skip the test if we can't
+        # find one.  The 'maximum' comes from here:
+        #   https://support.microsoft.com/en-us/kb/100111
+        found_com_device = False
+        for i in range(256):
+            try:
+                handle = CreateFile(
+                    "\\\\.\\COM%d" % i,
+                    library.GENERIC_READ | library.GENERIC_WRITE,
+                    dwCreationDisposition=library.OPEN_EXISTING,
+                    dwShareMode=0
+                )
+                found_com_device = True
+                self.addCleanup(CloseHandle, handle)
+                ClearCommError(handle)
+                break
+            except WindowsAPIError:
+                code, _ = ffi.getwinerror()
+                if code != library.ERROR_FILE_NOT_FOUND:
+                    self.fail("Unexpected Windows API error: %s" % code)
+
+        if not found_com_device:
+            self.skipTest("No COM devices present.")