gh-127255: Make `CopyComPointer` public and add to `ctypes` doc. (GH-127275)

1 files changed, 18 insertions, 0 deletions

diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index bd9529d..bd88fa3 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -1949,6 +1949,24 @@ Utility functions
    It behaves similar to ``pointer(obj)``, but the construction is a lot faster.
 
 
+.. function:: CopyComPointer(src, dst)
+
+   Copies a COM pointer from *src* to *dst* and returns the Windows specific
+   :c:type:`!HRESULT` value.
+
+   If *src* is not ``NULL``, its ``AddRef`` method is called, incrementing the
+   reference count.
+
+   In contrast, the reference count of *dst* will not be decremented before
+   assigning the new value. Unless *dst* is ``NULL``, the caller is responsible
+   for decrementing the reference count by calling its ``Release`` method when
+   necessary.
+
+   .. availability:: Windows
+
+   .. versionadded:: next
+
+
 .. function:: cast(obj, type)
 
    This function is similar to the cast operator in C. It returns a new instance