"ctypes" --- Python 用の外部関数ライブラリ
******************************************

**ソースコード:** Lib/ctypes

======================================================================

"ctypes" は Python 用の外部関数ライブラリです。 C と互換性のあるデータ
型を提供し、DLL や共有ライブラリの関数を呼び出せます。 これらのライブ
ラリを純粋な Python でラップするために使えます。

これは *optional module* です。 お使いの CPython に含まれていない場合
は、配布元 (Python を提供した組織や個人) のドキュメントを確認してくだ
さい。 配布する側の場合は、オプションのモジュールの要件 を参照してくだ
さい。

警告:

  "ctypes" は、Python の安全機構を迂回してネイティブライブラリやプロセ
  スのメモリに低水準でアクセスし、任意のネイティブコードを実行できるよ
  うにします。 使い方を誤ると、データやオブジェクトの破損、機密情報の
  漏えい、クラッシュなど、実行中のプロセスの安全性を損なう事態を引き起
  こす可能性があります。


ctypes チュートリアル
=====================

注意: いくつかのコードサンプルで ctypes の "c_int" 型を参照しています
。 "sizeof(long) == sizeof(int)" であるようなプラットフォームでは、こ
の型は "c_long" のエイリアスです。そのため、 "c_int" 型を想定している
ときに "c_long" が表示されたとしても、混乱しないようにしてください ---
実際には同じ型なのです。


動的リンクライブラリをロードする
--------------------------------

"ctypes" は、動的リンクライブラリをロードするための "cdll" オブジェク
トをエクスポートします。 Windows では "windll" と "oledll" オブジェク
トもエクスポートします。

これらのオブジェクトの属性にアクセスすると、ライブラリをロードできます
。 "cdll" は標準の "cdecl" 呼び出し規約で関数をエクスポートするライブ
ラリをロードし、"windll" のライブラリは "stdcall" 呼び出し規約で関数を
呼び出します。 "oledll" も "stdcall" 呼び出し規約を使用し、関数が
Windows の "HRESULT" エラーコードを返すと仮定します。 関数呼び出しが失
敗した場合は、このエラーコードを使って "OSError" 例外を自動的に送出し
ます。

バージョン 3.3 で変更: Windows エラーは以前は "WindowsError" を送出し
ていましたが、これは現在では "OSError" の別名になっています。

Windows での例を示します。 "msvcrt" は、標準 C 関数の大半を含む MS 標
準 C ライブラリで、"cdecl" 呼び出し規約を使用します。

   >>> from ctypes import *
   >>> print(windll.kernel32)
   <WinDLL 'kernel32', handle ... at ...>
   >>> print(cdll.msvcrt)
   <CDLL 'msvcrt', handle ... at ...>
   >>> libc = cdll.msvcrt
   >>>

Windows では通常の ".dll" ファイル拡張子を自動的に追加します。

注釈:

  "cdll.msvcrt" 経由で標準 C ライブラリにアクセスすると、Python が使用
  しているライブラリとは互換性のない可能性のある、古いバージョンのライ
  ブラリが使用されます。可能な場合には、ネイティブ Python の機能を使用
  するか、"msvcrt" モジュールをインポートして使用してください。

ほかのシステムでは、ライブラリのロードに拡張子を *含む* ファイル名が必
要なため、属性へのアクセスではロードできません。 DLL ローダーの
"LoadLibrary()" メソッドを使うか、コンストラクタを呼び出して "CDLL" イ
ンスタンスを作成し、ライブラリをロードしてください。

例えば、Linux では次のようにします。

   >>> cdll.LoadLibrary("libc.so.6")
   <CDLL 'libc.so.6', handle ... at ...>
   >>> libc = CDLL("libc.so.6")
   >>> libc
   <CDLL 'libc.so.6', handle ... at ...>
   >>>

macOS では次のようにします。

   >>> cdll.LoadLibrary("libc.dylib")
   <CDLL 'libc.dylib', handle ... at ...>
   >>> libc = CDLL("libc.dylib")
   >>> libc
   <CDLL 'libc.dylib', handle ... at ...>


ロードしたdllから関数にアクセスする
-----------------------------------

dll オブジェクトの属性として関数にアクセスします:

   >>> libc.printf
   <_FuncPtr object at 0x...>
   >>> print(windll.kernel32.GetModuleHandleA)
   <_FuncPtr object at 0x...>
   >>> print(windll.kernel32.MyOwnFunction)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File "ctypes.py", line 239, in __getattr__
       func = _StdcallFuncPtr(name, self)
   AttributeError: function 'MyOwnFunction' not found
   >>>

"kernel32" や "user32" などの win32 システム DLL は、関数の ANSI 版と
UNICODE 版を両方エクスポートすることがよくあります。 UNICODE 版は名前
の末尾に "W"、ANSI 版は "A" を付けてエクスポートされます。 指定したモ
ジュール名の *モジュールハンドル* を返す win32 の "GetModuleHandle" 関
数には、以下の C プロトタイプがあります。 UNICODE が定義されているかど
うかに応じて、マクロが一方を "GetModuleHandle" として公開します。

   /* ANSI 版 */
   HMODULE GetModuleHandleA(LPCSTR lpModuleName);
   /* UNICODE 版 */
   HMODULE GetModuleHandleW(LPCWSTR lpModuleName);

*windll* は魔法を使ってどちらか一つを選ぶようなことはしません。
"GetModuleHandleA" もしくは "GetModuleHandleW" を明示的に指定して必要
とするバージョンにアクセスし、バイト列か文字列を使ってそれぞれ呼び出さ
なければなりません。

時には、 dll が関数を ""??2@YAPAXI@Z"" のような Python 識別子として有
効でない名前でエクスポートすることがあります。このような場合に関数を取
り出すには、 "getattr()" を使わなければなりません。:

   >>> getattr(cdll.msvcrt, "??2@YAPAXI@Z")
   <_FuncPtr object at 0x...>
   >>>

Windows では、名前ではなく序数によって関数をエクスポートする dll もあ
ります。こうした関数には序数を使って dll オブジェクトにインデックス指
定することでアクセスします:

   >>> cdll.kernel32[1]
   <_FuncPtr object at 0x...>
   >>> cdll.kernel32[0]
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File "ctypes.py", line 310, in __getitem__
       func = _StdcallFuncPtr(name, self)
   AttributeError: function ordinal 0 not found
   >>>


関数を呼び出す
--------------

これらの関数は、ほかの Python の呼び出し可能オブジェクトと同じように呼
び出せます。 この例では、引数を取らず疑似乱数の整数を返す "rand()" 関
数を使います。

   >>> print(libc.rand())
   1804289383

Windows では、win32 モジュールハンドルを返す "GetModuleHandleA()" 関数
を呼び出せます (唯一の引数に "None" を渡すと、"NULL" ポインタを渡して
呼び出せます)。

   >>> print(hex(windll.kernel32.GetModuleHandleA(None)))
   0x1d000000
   >>>

"ctypes" は関数の呼び出し規約やシグネチャを判定できません。 関数の C
ヘッダーファイルやドキュメントを確認して正しい呼び出し規約を選び、要求
される引数の型を指定する (関数プロトタイプ) で説明する "argtypes" 属性
を設定してください。 "argtypes" を指定しないと、引数の数は検査されませ
ん。 誤った呼び出し規約や引数で関数を呼び出すと、メモリが破損したり
Python がクラッシュしたりする可能性があります。

Windows では、"ctypes" は win32 の構造化例外処理を使い、無効な引数の値
で関数を呼び出した際の一般保護違反によるクラッシュを防ぎます。

   >>> windll.kernel32.GetModuleHandleA(32)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   OSError: exception: access violation reading 0x00000020
   >>>

"faulthandler" モジュールは、C ライブラリの誤った呼び出しによるセグメ
ンテーション違反などのクラッシュのデバッグに役立ちます。

これらの関数呼び出しに引数として直接渡せる Python 標準のオブジェクトは
、"None"、整数、バイト列オブジェクト、(Unicode) 文字列だけです。
"None" は C の "NULL" ポインタとして渡され、バイト列オブジェクトと文字
列は、データを格納するメモリブロックへのポインタ (char* または
wchar_t*) として渡されます。 Python の整数は、プラットフォームのデフォ
ルトの C int 型として渡され、その C 型に収まるよう値がマスクされます。

ほかの型の引数を使って関数を呼び出す前に、"ctypes" のデータ型を詳しく
見ておく必要があります。


基本データ型
------------

"ctypes" は、C と互換性のある基本データ型をいくつも定義しています:

+---------------------------+---------------------------+---------------------------+---------------------------+
| ctypes の型               | C の型                    | Python の型               | "_type_"                  |
|===========================|===========================|===========================|===========================|
| "c_bool"                  | _Bool                     | "bool"                    | "'?'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_char"                  | char                      | 1 文字の "bytes"          | "'c'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_wchar"                 | "wchar_t"                 | 1 文字の "str"            | "'u'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_byte"                  | char                      | "int"                     | "'b'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_ubyte"                 | unsigned char             | "int"                     | "'B'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_short"                 | short                     | "int"                     | "'h'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_ushort"                | unsigned short            | "int"                     | "'H'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_int"                   | int                       | "int"                     | "'i'" *                   |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_int8"                  | "int8_t"                  | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_int16"                 | "int16_t"                 | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_int32"                 | "int32_t"                 | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_int64"                 | "int64_t"                 | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_uint"                  | unsigned int              | "int"                     | "'I'" *                   |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_uint8"                 | "uint8_t"                 | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_uint16"                | "uint16_t"                | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_uint32"                | "uint32_t"                | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_uint64"                | "uint64_t"                | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_long"                  | long                      | "int"                     | "'l'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_ulong"                 | unsigned long             | "int"                     | "'L'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_longlong"              | long long                 | "int"                     | "'q'" *                   |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_ulonglong"             | unsigned long long        | "int"                     | "'Q'" *                   |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_size_t"                | "size_t"                  | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_ssize_t"               | "Py_ssize_t"              | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_time_t"                | "time_t"                  | "int"                     | *                         |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_float"                 | float                     | "float"                   | "'f'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_double"                | double                    | "float"                   | "'d'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_longdouble"            | long double               | "float"                   | "'g'" *                   |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_char_p"                | char* (NUL 終端)          | "bytes" または "None"     | "'z'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_wchar_p"               | wchar_t* (NUL 終端)       | "str" または "None"       | "'Z'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_void_p"                | void*                     | "int" または "None"       | "'P'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "py_object"               | PyObject*                 | "object"                  | "'O'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+
| VARIANT_BOOL              | short int                 | "bool"                    | "'v'"                     |
+---------------------------+---------------------------+---------------------------+---------------------------+

さらに、C と "libffi" の両方が IEC 60559 に準拠した複素数演算 (附属書
G) をサポートする場合、以下の複素数型を利用できます:

+---------------------------+---------------------------+---------------------------+---------------------------+
| ctypes の型               | C の型                    | Python の型               | "_type_"                  |
|===========================|===========================|===========================|===========================|
| "c_float_complex"         | float complex             | "complex"                 | "'Zf'"                    |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_double_complex"        | double complex            | "complex"                 | "'Zd'"                    |
+---------------------------+---------------------------+---------------------------+---------------------------+
| "c_longdouble_complex"    | long double complex       | "complex"                 | "'Zg'"                    |
+---------------------------+---------------------------+---------------------------+---------------------------+

バージョン 3.15 で変更: "_type_" の型 "F"、"D"、"G" は、"Zf"、"Zd"、
"Zg" に置き換えられました。

これら全ての型はその型を呼び出すことによって作成でき、オプションとして
型と値が合っている初期化子を指定することができます:

   >>> c_int()
   c_long(0)
   >>> c_wchar_p("Hello, World")
   c_wchar_p(140018365411392)
   >>> c_ushort(-3)
   c_ushort(65533)
   >>>

数値型のコンストラクタは、"__bool__()"、"__index__()" ("int" の場合)、
"__float__()"、"__complex__()" を使って入力を変換します。 したがって、
"c_bool" は真偽値を持つ任意のオブジェクトを受け付けます。

   >>> empty_list = []
   >>> c_bool(empty_list)
   c_bool(False)

これらの型は変更可能であり、値を後で変更することもできます:

   >>> i = c_int(42)
   >>> print(i)
   c_long(42)
   >>> print(i.value)
   42
   >>> i.value = -99
   >>> print(i.value)
   -99
   >>>

ポインタ型 "c_char_p"、"c_wchar_p"、"c_void_p" のインスタンスに新しい
値を代入すると、そのポインタが指す *メモリ位置* が変わり、メモリブロッ
クの *内容は変わりません* (Python の文字列オブジェクトは不変なので、当
然の動作です)。

   >>> s = "Hello, World"
   >>> c_s = c_wchar_p(s)
   >>> print(c_s)
   c_wchar_p(139966785747344)
   >>> print(c_s.value)
   Hello World
   >>> c_s.value = "Hi, there"
   >>> print(c_s)              # the memory location has changed
   c_wchar_p(139966783348904)
   >>> print(c_s.value)
   Hi, there
   >>> print(s)                # first object is unchanged
   Hello, World
   >>>

しかし、変更可能なメモリを指すポインタであることを想定している関数へそ
れらを渡さないように注意すべきです。もし変更可能なメモリブロックが必要
なら、 ctypes には "create_string_buffer()" 関数があり、いろいろな方法
で作成することできます。現在のメモリブロックの内容は "raw" プロパティ
を使ってアクセス (あるいは変更) することができます。もし現在のメモリブ
ロックに NUL 終端文字列としてアクセスしたいなら、 "value" プロパティを
使ってください:

   >>> from ctypes import *
   >>> p = create_string_buffer(3)            # NUL バイトで初期化した 3 バイトのバッファを作成します
   >>> print(sizeof(p), repr(p.raw))
   3 b'\x00\x00\x00'
   >>> p = create_string_buffer(b"Hello")     # NUL 終端文字列を含むバッファを作成します
   >>> print(sizeof(p), repr(p.raw))
   6 b'Hello\x00'
   >>> print(repr(p.value))
   b'Hello'
   >>> p = create_string_buffer(b"Hello", 10) # 10 バイトのバッファを作成します
   >>> print(sizeof(p), repr(p.raw))
   10 b'Hello\x00\x00\x00\x00\x00'
   >>> p.value = b"Hi"
   >>> print(sizeof(p), repr(p.raw))
   10 b'Hi\x00lo\x00\x00\x00\x00\x00'
   >>>

"create_string_buffer()" 関数は、古い "c_buffer()" 関数を置き換えるも
のです (後者は別名として引き続き利用できます)。 C の "wchar_t" 型の
Unicode 文字を格納する変更可能なメモリブロックを作成するには、
"create_unicode_buffer()" 関数を使ってください。


続・関数を呼び出す
------------------

printf は "sys.stdout" では *なく* 、本物の標準出力チャンネルへプリン
トすることに注意してください。したがって、これらの例はコンソールプロン
プトでのみ動作し、 *IDLE* や *PythonWin* では動作しません。:

   >>> printf = libc.printf
   >>> printf(b"Hello, %s\n", b"World!")
   Hello, World!
   14
   >>> printf(b"Hello, %S\n", "World!")
   Hello, World!
   14
   >>> printf(b"%d bottles of beer\n", 42)
   42 bottles of beer
   19
   >>> printf(b"%f bottles of beer\n", 42.5)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ctypes.ArgumentError: argument 2: TypeError: Don't know how to convert parameter 2
   >>>

前述のとおり、整数、文字列、バイト列オブジェクト以外の Python の型は、
必要な C のデータ型に変換できるよう、対応する "ctypes" の型でラップす
る必要があります。

   >>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))
   An int 1234, a double 3.140000
   31
   >>>


可変長引数関数の呼び出し
------------------------

多くのプラットフォームでは、ctypes を使った可変長引数関数の呼び出し方
は、引数の数が固定の関数とまったく同じです。 一部のプラットフォーム、
特に Apple プラットフォームの ARM64 では、可変長引数関数の呼び出し規約
が通常の関数とは異なります。

それらのプラットフォームでは、可変長ではない通常の引数について
"argtypes" 属性を指定する必要があります:

   libc.printf.argtypes = [ctypes.c_char_p]

この属性の指定は移植性を損なわないため、すべての可変長引数関数について
常に "argtypes" を指定することを推奨します。


自作のデータ型とともに関数を呼び出す
------------------------------------

"ctypes" の引数変換をカスタマイズして、自作クラスのインスタンスを関数
の引数として使うこともできます。 "ctypes" は "_as_parameter_" 属性を探
し、その値を関数の引数として使用します。 この属性は、整数、文字列、バ
イト列、"ctypes" のインスタンス、または "_as_parameter_" 属性を持つオ
ブジェクトでなければなりません。

   >>> class Bottles:
   ...     def __init__(self, number):
   ...         self._as_parameter_ = number
   ...
   >>> bottles = Bottles(42)
   >>> printf(b"%d bottles of beer\n", bottles)
   42 bottles of beer
   19
   >>>

インスタンスのデータを "_as_parameter_" インスタンス変数に保存したくな
い場合は、アクセス時に属性値を提供する "@property" を定義できます。


要求される引数の型を指定する (関数プロトタイプ)
-----------------------------------------------

DLL がエクスポートする関数の引数に必要な型は、"argtypes" 属性を設定し
て指定できます。

"argtypes" は C のデータ型のシーケンスでなければなりません ("printf()"
関数は、書式文字列に応じて引数の数や型が変わるので、ここでは良い例とは
いえませんが、この機能を試すには便利です)。

   >>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]
   >>> printf(b"String '%s', Int %d, Double %f\n", b"Hi", 10, 2.2)
   String 'Hi', Int 10, Double 2.200000
   37
   >>>

(C の関数のプロトタイプのように) 書式を指定すると互換性のない引数型に
なるのを防ぎ、引数を有効な型へ変換しようとします。:

   >>> printf(b"%d %d %d", 1, 2, 3)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   ctypes.ArgumentError: argument 2: TypeError: 'int' object cannot be interpreted as ctypes.c_char_p
   >>> printf(b"%s %d %f\n", b"X", 2, 3)
   X 2 3.000000
   13
   >>>

"argtypes" を設定すると、渡された引数が少なすぎる場合に "ctypes" が
"TypeError" を送出するようにもなります。

   >>> printf(b"%s %d %f\n", b"X", 2)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: this function takes at least 4 arguments (3 given)

"stdcall" 呼び出し規約を使う関数には、"argtypes" の要素数とまったく同
じ数の引数が必要です。 "cdecl" 呼び出し規約を使う関数は、可変長引数関
数をサポートするため、追加の引数を受け付けます。 宣言は関数の実際のシ
グネチャに一致する必要がありますが、ctypes はそれを検証できません。

関数呼び出しに渡すための独自クラスを定義した場合、そのクラスを
"argtypes" シーケンスで使うには "from_param()" クラスメソッドを実装す
る必要があります。 "from_param()" クラスメソッドは、関数呼び出しに渡さ
れた Python オブジェクトを受け取ります。 型検査など、オブジェクトを受
け付けられることを確認するための処理を行い、オブジェクト自身、その
"_as_parameter_" 属性、または C 関数の引数として渡したい値を返してくだ
さい。 この場合も、戻り値は整数、文字列、バイト列、"ctypes" のインスタ
ンス、または "_as_parameter_" 属性を持つオブジェクトである必要がありま
す。


戻り値の型
----------

デフォルトでは、関数は C の int 型を返すと仮定します。 関数オブジェク
トの "restype" 属性を設定すれば、ほかの戻り値の型を指定できます。

"time()" の C プロトタイプは "time_t time(time_t *)" です。 "time_t"
は、デフォルトの戻り値の型 int と異なる場合があるため、"restype" 属性
を指定する必要があります。

   >>> libc.time.restype = c_time_t

引数の型は "argtypes" を使って指定できます。

   >>> libc.time.argtypes = (POINTER(c_time_t),)

第 1 引数に "NULL" ポインタを渡して関数を呼び出すには、"None" を使いま
す。

   >>> print(libc.time(None))
   1150640792

もう少し高度な例として、文字列へのポインタと char を受け取り、文字列へ
のポインタを返す "strchr()" 関数を使います。

   >>> strchr = libc.strchr
   >>> strchr(b"abcdef", ord("d"))
   8059983
   >>> strchr.restype = c_char_p    # c_char_p is a pointer to a string
   >>> strchr(b"abcdef", ord("d"))
   b'def'
   >>> print(strchr(b"abcdef", ord("x")))
   None
   >>>

上の例の "ord("x")" の呼び出しを省くには、"argtypes" 属性を設定します
。 これにより、第 2 引数が 1 文字の Python バイト列オブジェクトから C
の char に変換されます:

   >>> strchr.restype = c_char_p
   >>> strchr.argtypes = [c_char_p, c_char]
   >>> strchr(b"abcdef", b"d")
   b'def'
   >>> strchr(b"abcdef", b"def")
   Traceback (most recent call last):
   ctypes.ArgumentError: argument 2: TypeError: one character bytes, bytearray or integer expected
   >>> print(strchr(b"abcdef", b"x"))
   None
   >>> strchr(b"abcdef", b"d")
   b'def'
   >>>

外部関数が整数を返す場合、"restype" 属性に、関数やクラスなどの Python
の呼び出し可能オブジェクトを使うこともできます。 C 関数が返した *整数*
を引数としてそのオブジェクトが呼び出され、その結果が関数呼び出しの結果
として使われます。 これは、戻り値のエラーを検査して例外を自動的に送出
するのに役立ちます。

   >>> GetModuleHandle = windll.kernel32.GetModuleHandleA
   >>> def ValidHandle(value):
   ...     if value == 0:
   ...         raise WinError()
   ...     return value
   ...
   >>>
   >>> GetModuleHandle.restype = ValidHandle
   >>> GetModuleHandle(None)
   486539264
   >>> GetModuleHandle("something silly")
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File "<stdin>", line 3, in ValidHandle
   OSError: [Errno 126] The specified module could not be found.
   >>>

"WinError" はエラーコードの文字列表現を得るために Windows の
"FormatMessage()" api を呼び出し、例外を *返す* 関数です。 "WinError"
はオプションでエラーコードパラメータを取ります。このパラメータが使われ
ない場合は、エラーコードを取り出すために "GetLastError()" を呼び出しま
す。

"errcheck" 属性を使うと、さらに強力なエラー検査の仕組みを利用できます
。 詳細はリファレンスマニュアルを参照してください。


ポインタを渡す(または、パラメータの参照渡し)
--------------------------------------------

時には、 C api 関数がパラメータのデータ型として *ポインタ* を想定して
いることがあります。おそらくパラメータと同一の場所に書き込むためか、も
しくはそのデータが大きすぎて値渡しできない場合です。これは *パラメータ
の参照渡し* としても知られています。

"ctypes" は、引数を参照渡しするための "byref()" 関数をエクスポートしま
す。 "pointer()" 関数でも同じ効果を得られますが、"pointer()" は実際の
ポインタオブジェクトを構築するため、より多くの処理を行います。 Python
側でポインタオブジェクト自体が必要なければ、"byref()" の方が高速です。

   >>> i = c_int()
   >>> f = c_float()
   >>> s = create_string_buffer(b'\000' * 32)
   >>> print(i.value, f.value, repr(s.value))
   0 0.0 b''
   >>> libc.sscanf(b"1 3.14 Hello", b"%d %f %s",
   ...             byref(i), byref(f), s)
   3
   >>> print(i.value, f.value, repr(s.value))
   1 3.1400001049 b'Hello'
   >>>


構造体と共用体
--------------

構造体と共用体は、"ctypes" モジュールが定義する "Structure" と "Union"
の基底クラスから派生させる必要があります。 各サブクラスには "_fields_"
属性を定義する必要があります。 "_fields_" は、*フィールド名* と *フィ
ールドの型* を含む *2 要素のタプル* のリストでなければなりません。

フィールドの型は、"c_int" などの "ctypes" の型、または構造体、共用体、
配列、ポインタなど、ほかの派生した "ctypes" の型でなければなりません。

以下は、 *x* と *y* という名前の二つの整数からなる簡単な POINT 構造体
の例です。コンストラクタで構造体を初期化する方法も説明しています:

   >>> from ctypes import *
   >>> class POINT(Structure):
   ...     _fields_ = [("x", c_int),
   ...                 ("y", c_int)]
   ...
   >>> point = POINT(10, 20)
   >>> print(point.x, point.y)
   10 20
   >>> point = POINT(y=5)
   >>> print(point.x, point.y)
   0 5
   >>> POINT(1, 2, 3)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: too many initializers
   >>>

しかし、もっと複雑な構造体を構築することもできます。ある構造体は、他の
構造体をフィールド型として使うことで、他の構造体を含むことができます。

*upperleft* と *lowerright* という名前の二つの POINT を持つ RECT 構造
体です。:

   >>> class RECT(Structure):
   ...     _fields_ = [("upperleft", POINT),
   ...                 ("lowerright", POINT)]
   ...
   >>> rc = RECT(point)
   >>> print(rc.upperleft.x, rc.upperleft.y)
   0 5
   >>> print(rc.lowerright.x, rc.lowerright.y)
   0 0
   >>>

入れ子になった構造体はいくつかの方法を用いてコンストラクタで初期化する
ことができます。:

   >>> r = RECT(POINT(1, 2), POINT(3, 4))
   >>> r = RECT((1, 2), (3, 4))

フィールドの *descriptor* は *クラス* から取得でき、有用な情報を提供す
るためデバッグに役立ちます。 "CField" を参照してください。

   >>> POINT.x
   <ctypes.CField 'x' type=c_int, ofs=0, size=4>
   >>> POINT.y
   <ctypes.CField 'y' type=c_int, ofs=4, size=4>
   >>>

警告:

  "ctypes" は、共用体やビットフィールドを持つ構造体を関数に値渡しする
  ことをサポートしていません。 32 ビットの x86 では動作することもあり
  ますが、一般に動作することはライブラリでは保証していません。 共用体
  やビットフィールドを持つ構造体は、常にポインタとして関数に渡してくだ
  さい。


構造体と共用体のレイアウト、アラインメント、バイト順序
------------------------------------------------------

デフォルトでは、"Structure" と "Union" のフィールドは C コンパイラと同
じ方法で配置されます。 サブクラス定義で "_layout_" クラス属性を指定す
れば、この動作を完全に上書きできます。 詳細はこの属性のドキュメントを
参照してください。

It is possible to specify the maximum alignment for the fields and/or
for the structure itself by setting the class attributes "_pack_"
and/or "_align_", respectively. See the attribute documentation for
details.

"ctypes" は、構造体と共用体にネイティブのバイト順序を使用します。 ネイ
ティブでないバイト順序の構造体を作るには、"BigEndianStructure"、
"LittleEndianStructure"、"BigEndianUnion"、"LittleEndianUnion" のいず
れかを基底クラスとして使えます。 これらのクラスにはポインタフィールド
を含められません。


構造体と共用体におけるビットフィールド
--------------------------------------

ビットフィールドを含む構造体や共用体も作成できます。 ビットフィールド
にできるのは整数フィールドだけで、ビット幅は "_fields_" のタプルの第 3
要素として指定します。

   >>> class Int(Structure):
   ...     _fields_ = [("first_16", c_int, 16),
   ...                 ("second_16", c_int, 16)]
   ...
   >>> print(Int.first_16)
   <ctypes.CField 'first_16' type=c_int, ofs=0, bit_size=16, bit_offset=0>
   >>> print(Int.second_16)
   <ctypes.CField 'second_16' type=c_int, ofs=0, bit_size=16, bit_offset=16>

ビットフィールドのメモリ内での割り当てやレイアウトは C 標準では定義さ
れておらず、コンパイラ固有の実装であることに注意してください。 デフォ
ルトでは、Python は現在のプラットフォームの「ネイティブ」コンパイラの
動作に合わせようとします。 デフォルトの動作とその変更方法については、
"_layout_" 属性を参照してください。


配列
----

配列 (Array) はシーケンスであり、決まった数の同じ型のインスタンスを持
ちます。

推奨されている配列の作成方法はデータ型に正の整数を掛けることです。:

   TenPointsArrayType = POINT * 10

ややわざとらしいデータ型の例になりますが、他のものに混ざって 4 個の
POINT がある構造体です:

   >>> from ctypes import *
   >>> class POINT(Structure):
   ...     _fields_ = ("x", c_int), ("y", c_int)
   ...
   >>> class MyStruct(Structure):
   ...     _fields_ = [("a", c_int),
   ...                 ("b", c_float),
   ...                 ("point_array", POINT * 4)]
   >>>
   >>> print(len(MyStruct().point_array))
   4
   >>>

インスタンスはクラスを呼び出す通常の方法で作成します。:

   arr = TenPointsArrayType()
   for pt in arr:
       print(pt.x, pt.y)

上記のコードは "0 0" という行が並んだものを表示します。配列の要素がゼ
ロで初期化されているためです。

正しい型の初期化子を指定することもできます。:

   >>> from ctypes import *
   >>> TenIntegers = c_int * 10
   >>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
   >>> print(ii)
   <c_long_Array_10 object at 0x...>
   >>> for i in ii: print(i, end=" ")
   ...
   1 2 3 4 5 6 7 8 9 10
   >>>


ポインタ
--------

"ctypes" の型のオブジェクトに対して "pointer()" 関数を呼び出すと、ポイ
ンタインスタンスが作成されます。

   >>> from ctypes import *
   >>> i = c_int(42)
   >>> pi = pointer(i)
   >>>

次のように、ポインタインスタンスは、ポインタが指すオブジェクト (上の例
では "i") を返す "contents" 属性を持ちます:

   >>> pi.contents
   c_long(42)
   >>>

"ctypes" は OOR (元のオブジェクトを返すこと) を行いません。 属性を取得
するたびに、同等の新しいオブジェクトを構築します。

   >>> pi.contents is i
   False
   >>> pi.contents is pi.contents
   False
   >>>

別の "c_int" インスタンスがポインタの contents 属性に代入されると、こ
れが記憶されているメモリ位置を指すポインタに変化します。:

   >>> i = c_int(99)
   >>> pi.contents = i
   >>> pi.contents
   c_long(99)
   >>>

ポインタインスタンスは整数でインデックス指定することもできます。:

   >>> pi[0]
   99
   >>>

整数インデックスへ代入するとポインタが指す値が変更されます。:

   >>> print(i)
   c_long(99)
   >>> pi[0] = 22
   >>> print(i)
   c_long(22)
   >>>

0 ではないインデックスを使うこともできますが、 C の場合と同じように自
分が何をしているかを理解している必要があります。任意のメモリ位置にアク
セスもしくは変更できるのです。一般的にこの機能を使うのは、 C 関数から
ポインタを受け取り、そのポインタが単一の要素ではなく実際に配列を指して
いると *分かっている* 場合だけです。

警告:

  ポインタオブジェクトは添字付けをサポートするため、暗黙に *反復* もサ
  ポートします。 ただし、"pointer()" のイテレータに対して "next()" を
  手動で呼び出すなど、制御しながら使わないと、通常は無限ループやクラッ
  シュを引き起こします。 ctypes には反復をどこで終了すればよいか判断す
  る方法がないためです。 つまり、"pointer" のイテレータは任意のメモリ
  の内容を際限なく yield します。

"pointer()" 関数は、内部では単にポインタインスタンスを作るだけでなく、
まずポインタの *型* を作る必要があります。 これには、任意の "ctypes"
の型を受け取り、新しい型を返す "POINTER()" 関数を使います。

   >>> PI = POINTER(c_int)
   >>> PI
   <class 'ctypes.LP_c_long'>
   >>> PI(42)
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: expected c_long instead of int
   >>> PI(c_int(42))
   <ctypes.LP_c_long object at 0x...>
   >>>

ポインタ型を引数なしで呼び出すと "NULL" ポインタを作成します。 "NULL"
ポインタは "False" ブール値を持っています。:

   >>> null_ptr = POINTER(c_int)()
   >>> print(bool(null_ptr))
   False
   >>>

"ctypes" は、ポインタを参照外しする際に "NULL" かどうかを検査します (
ただし、"NULL" でない無効なポインタを参照外しすると Python はクラッシ
ュします)。

   >>> null_ptr[0]
   Traceback (most recent call last):
       ....
   ValueError: NULL pointer access
   >>>

   >>> null_ptr[0] = 1234
   Traceback (most recent call last):
       ....
   ValueError: NULL pointer access
   >>>


GIL のない環境でのスレッド安全性
--------------------------------

Python 3.13 以降では、*free-threaded build* で *GIL* を無効にできます
。 ctypes では、単一のオブジェクトに対する並行した読み書きは安全ですが
、複数のオブジェクトを通じた並行した読み書きは安全ではありません:

      >>> number = c_int(42)
      >>> pointer_a = pointer(number)
      >>> pointer_b = pointer(number)

上の例で GIL が無効の場合、同じアドレスに対して一度に安全に読み書きで
きるのは、1 つのオブジェクトだけです。 したがって、複数のスレッドで
"pointer_a" を共有して書き込むことはできますが、"pointer_b" が同じこと
をしようとしていない場合に限られます。 これが問題になる場合は、
"threading.Lock" を使ってメモリへのアクセスを同期することを検討してく
ださい:

      >>> import threading
      >>> lock = threading.Lock()
      >>> # Thread 1
      >>> with lock:
      ...    pointer_a.contents = 24
      >>> # Thread 2
      >>> with lock:
      ...    pointer_b.contents = 42


型変換
------

通常、ctypes は厳密な型検査を行います。 例えば、関数の "argtypes" リス
トや構造体定義のメンバーフィールドの型に "POINTER(c_int)" を指定した場
合、まったく同じ型のインスタンスしか受け付けません。 ただし、この規則
には例外があり、ctypes がほかのオブジェクトを受け付ける場合もあります
。 例えば、ポインタ型の代わりに、互換性のある配列インスタンスを渡せま
す。 そのため、"POINTER(c_int)" に対しては、ctypes は c_int の配列を受
け付けます。

   >>> class Bar(Structure):
   ...     _fields_ = [("count", c_int), ("values", POINTER(c_int))]
   ...
   >>> bar = Bar()
   >>> bar.values = (c_int * 3)(1, 2, 3)
   >>> bar.count = 3
   >>> for i in range(bar.count):
   ...     print(bar.values[i])
   ...
   1
   2
   3
   >>>

さらに、"argtypes" で関数の引数を "POINTER(c_int)" などのポインタ型と
して明示的に宣言した場合、参照先の型 (この場合は "c_int") のオブジェク
トを関数に渡せます。 この場合、ctypes は必要な "byref()" 変換を自動的
に適用します。

POINTER型フィールドを "NULL" に設定するために、 "None" を代入してもか
まいません。:

   >>> bar.values = None
   >>>

互換性のない型のインスタンスを扱うこともあります。 C では、ある型を別
の型にキャストできます。 "ctypes" には、同じように使える "cast()" 関数
があります。 上で定義した "Bar" 構造体の "values" フィールドは、
"POINTER(c_int)" ポインタや "c_int" 配列を受け付けますが、ほかの型のイ
ンスタンスは受け付けません。

   >>> bar.values = (c_byte * 4)()
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
   >>>

このような場合には、 "cast()" 関数が便利です。

"cast()" 関数は ctypes インスタンスを異なる ctypes データ型を指すポイ
ンタへキャストするために使えます。 "cast()" は二つのパラメータ、ある種
のポインタかそのポインタへ変換できる ctypes オブジェクトと、 ctypes ポ
インタ型を取ります。そして、第二引数のインスタンスを返します。このイン
スタンスは第一引数と同じメモリブロックを参照しています:

   >>> a = (c_byte * 4)()
   >>> cast(a, POINTER(c_int))
   <ctypes.LP_c_long object at ...>
   >>>

したがって、 "cast()" を "Bar" 構造体の "values" フィールドへ代入する
ために使うことができます:

   >>> bar = Bar()
   >>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
   >>> print(bar.values[0])
   0
   >>>


不完全型
--------

*不完全型* はメンバーがまだ指定されていない構造体、共用体もしくは配列
です。 C では、前方宣言により指定され、後で定義されます。:

   struct cell; /* 前方宣言 */

   struct cell {
       char *name;
       struct cell *next;
   };

ctypes コードへの直接的な変換ではこうなるでしょう。しかし、動作しませ
ん:

   >>> class cell(Structure):
   ...     _fields_ = [("name", c_char_p),
   ...                 ("next", POINTER(cell))]
   ...
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File "<stdin>", line 2, in cell
   NameError: name 'cell' is not defined
   >>>

これは、新しい "class cell" が、そのクラス文の内部ではまだ利用できない
ためです。 "ctypes" では、まず "cell" クラスを定義し、クラス文の後で
"_fields_" 属性を設定できます。

   >>> from ctypes import *
   >>> class cell(Structure):
   ...     pass
   ...
   >>> cell._fields_ = [("name", c_char_p),
   ...                  ("next", POINTER(cell))]
   >>>

試してみましょう。 "cell" のインスタンスを二つ作り、互いに参照し合うよ
うにします。最後に、つながったポインタを何度かたどります。:

   >>> c1 = cell()
   >>> c1.name = b"foo"
   >>> c2 = cell()
   >>> c2.name = b"bar"
   >>> c1.next = pointer(c2)
   >>> c2.next = pointer(c1)
   >>> p = c1
   >>> for i in range(8):
   ...     print(p.name, end=" ")
   ...     p = p.next[0]
   ...
   foo bar foo bar foo bar foo bar
   >>>


コールバック関数
----------------

"ctypes" を使うと、Python の呼び出し可能オブジェクトから、C で呼び出せ
る関数ポインタを作成できます。 これらは *コールバック関数* と呼ばれる
こともあります。

最初に、コールバック関数のためのクラスを作る必要があります。そのクラス
には呼び出し規約、戻り値の型およびこの関数が受け取る引数の数と型につい
ての情報があります。

"CFUNCTYPE()" ファクトリ関数は通常の "cdecl" 呼び出し規約を用いてコー
ルバック関数のための型を作成します。 Windows では、 "WINFUNCTYPE()" フ
ァクトリ関数が "stdcall" 呼び出し規約を用いてコールバック関数の型を作
成します。

これらのファクトリ関数はともに最初の引数に戻り値の型、残りの引数として
コールバック関数が想定する引数の型を渡して呼び出されます。

ここでは、標準 C ライブラリの "qsort()" 関数を使う例を示します。 この
関数は、コールバック関数を使って要素をソートします。 "qsort()" で整数
の配列をソートしてみます。

   >>> IntArray5 = c_int * 5
   >>> ia = IntArray5(5, 1, 7, 33, 99)
   >>> qsort = libc.qsort
   >>> qsort.restype = None
   >>>

"qsort()" は、ソートするデータへのポインタ、データ配列の要素数、1 要素
のサイズ、比較関数であるコールバックへのポインタを渡して呼び出す必要が
あります。 コールバックは、要素への 2 つのポインタを引数として呼び出さ
れます。 最初の要素が 2 番目より小さければ負の整数、等しければゼロ、そ
れ以外なら正の整数を返す必要があります。

コールバック関数は整数へのポインタを受け取り、整数を返す必要があります
。まず、コールバック関数のための "type" を作成します。:

   >>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
   >>>

まず初めに、これが受け取った変数を表示するだけのシンプルなコールバック
です:

   >>> def py_cmp_func(a, b):
   ...     print("py_cmp_func", a[0], b[0])
   ...     return 0
   ...
   >>> cmp_func = CMPFUNC(py_cmp_func)
   >>>

結果は以下の通りです:

   >>> qsort(ia, len(ia), sizeof(c_int), cmp_func)
   py_cmp_func 5 1
   py_cmp_func 33 99
   py_cmp_func 7 33
   py_cmp_func 5 7
   py_cmp_func 1 7
   >>>

ここで 2 つの要素を実際に比較し、役に立つ結果を返します:

   >>> def py_cmp_func(a, b):
   ...     print("py_cmp_func", a[0], b[0])
   ...     return a[0] - b[0]
   ...
   >>>
   >>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func))
   py_cmp_func 5 1
   py_cmp_func 33 99
   py_cmp_func 7 33
   py_cmp_func 1 7
   py_cmp_func 5 7
   >>>

簡単に確認できるように、配列を次のようにソートしました:

   >>> for i in ia: print(i, end=" ")
   ...
   1 5 7 33 99
   >>>

関数ファクトリはデコレータファクトリとしても使えるので、次のようにも書
けます:

   >>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
   ... def py_cmp_func(a, b):
   ...     print("py_cmp_func", a[0], b[0])
   ...     return a[0] - b[0]
   ...
   >>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)
   py_cmp_func 5 1
   py_cmp_func 33 99
   py_cmp_func 7 33
   py_cmp_func 1 7
   py_cmp_func 5 7
   >>>

注釈:

  C コードで使用されている間は、必ず "CFUNCTYPE()" オブジェクトへの参
  照を保持してください。 "ctypes" 自身は参照を保持しないため、参照を保
  持しないとオブジェクトがガベージコレクションされ、コールバックの呼び
  出し時にプログラムがクラッシュする可能性があります。同様に、コールバ
  ック関数が Python の管理外 (例えば、コールバックを呼び出す外部のコー
  ド) で作られたスレッドで呼び出された場合、 ctypes は全ての呼び出しご
  とに新しいダミーの Python スレッドを作成することに注意してください。
  この動作はほとんどの目的に対して正しいものですが、同じ C スレッドか
  らの呼び出しだったとしても、 "threading.local" で格納された値は異な
  るコールバックをまたいで生存は *しません* 。


dllからエクスポートされた値へアクセスする
-----------------------------------------

共有ライブラリには、関数だけでなく変数もエクスポートするものがあります
。 Python ライブラリ自体にも例があり、"Py_Version" は Python ランタイ
ムのバージョン番号を単一の定数の整数に符号化したものです。

"ctypes" は、型の "in_dll()" クラスメソッドを使って、このような値にア
クセスできます。 *pythonapi* は、Python C API へのアクセスを提供する定
義済みのシンボルです。

   >>> version = ctypes.c_int.in_dll(ctypes.pythonapi, "Py_Version")
   >>> print(hex(version.value))
   0x30c00a0

ポインタの使い方を説明する拡張例では、 Python がエクスポートする
"PyImport_FrozenModules" ポインタにアクセスします。

この値のドキュメントから引用すると:

   このポインタは "_frozen" のレコードからなり、終端の要素のメンバが
   "NULL" かゼロになっているような配列を指すよう初期化されます。 フリ
   ーズされたモジュールをインポートするとき、このテーブルを検索します
   。 サードパーティ製のコードからこのポインタに仕掛けを講じて、動的に
   生成されたフリーズ化モジュールの集合を提供するようにできます。

したがって、このポインタの操作は役立つこともあります。 例を短くするた
め、ここでは "ctypes" を使ってこのテーブルを読み取る方法だけを示します
。

   >>> from ctypes import *
   >>>
   >>> class struct_frozen(Structure):
   ...     _fields_ = [("name", c_char_p),
   ...                 ("code", POINTER(c_ubyte)),
   ...                 ("size", c_int),
   ...                 ("get_code", POINTER(c_ubyte)),  # Function pointer
   ...                ]
   ...
   >>>

私たちは "_frozen" データ型を定義済みなので、このテーブルを指すポイン
タを得ることができます。:

   >>> FrozenTable = POINTER(struct_frozen)
   >>> table = FrozenTable.in_dll(pythonapi, "_PyImport_FrozenBootstrap")
   >>>

"table" が "struct_frozen" レコードの配列への "pointer" なので、その配
列に対して反復処理を行えます。しかし、ループが確実に終了するようにする
必要があります。なぜなら、ポインタに大きさの情報がないからです。遅かれ
早かれ、アクセス違反か何かでクラッシュすることになるでしょう。 "NULL"
エントリに達したときはループを抜ける方が良いです:

   >>> for item in table:
   ...     if item.name is None:
   ...         break
   ...     print(item.name.decode("ascii"), item.size)
   ...
   _frozen_importlib 31764
   _frozen_importlib_external 41499
   zipimport 12345
   >>>

標準 Python はフローズンモジュールとフローズンパッケージ (負の "size"
メンバーで表されています) を持っているという事実はあまり知られておらず
、テストにだけ使われています。例えば、 "import __hello__" を試してみて
ください。


びっくり仰天
------------

"ctypes" には、実際とは異なる動作を期待してしまいがちな部分がいくつか
あります。

次に示す例について考えてみてください。:

   >>> from ctypes import *
   >>> class POINT(Structure):
   ...     _fields_ = ("x", c_int), ("y", c_int)
   ...
   >>> class RECT(Structure):
   ...     _fields_ = ("a", POINT), ("b", POINT)
   ...
   >>> p1 = POINT(1, 2)
   >>> p2 = POINT(3, 4)
   >>> rc = RECT(p1, p2)
   >>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
   1 2 3 4
   >>> # 2 つの点を交換します
   >>> rc.a, rc.b = rc.b, rc.a
   >>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
   3 4 3 4
   >>>

うーん、最後の文に "3 4 1 2" と表示されることを期待していたはずです。
何が起きたのでしょうか? 上の行の "rc.a, rc.b = rc.b, rc.a" の各段階は
このようになります。:

   >>> temp0, temp1 = rc.b, rc.a
   >>> rc.a = temp0
   >>> rc.b = temp1
   >>>

"temp0" と "temp1" は前記の "rc" オブジェクトの内部バッファを引き続き
使用しているオブジェクトです。 したがって、 "rc.a = temp0" を実行する
と "temp0" のバッファ内容が "rc" のバッファへコピーされます。 さらに、
これは "temp1" の内容を変更します。 そのため、最後の代入 "rc.b =
temp1" は、期待する結果にはならないのです。

Structure 、 Union および Array のサブオブジェクトを取り出しても、その
サブオブジェクトが *コピー* されるわけではなく、ルートオブジェクトの内
部バッファにアクセスするラッパーオブジェクトを取り出すことを覚えておい
てください。

期待とは違う振る舞いをする別の例はこれです:

   >>> s = c_char_p()
   >>> s.value = b"abc def ghi"
   >>> s.value
   b'abc def ghi'
   >>> s.value is s.value
   False
   >>>

注釈:

  "c_char_p" からインスタンス化されたオブジェクトは、bytes または整数
  に設定された値しか持てません。

なぜ "False" と表示されるのでしょうか? ctypes インスタンスはメモリと、
メモリの内容にアクセスするいくつかの *descriptor* (記述子)を含むオブジ
ェクトです。メモリブロックに Python オブジェクトを保存してもオブジェク
ト自身が保存される訳ではなく、オブジェクトの "contents" が保存されます
。その contents に再アクセスすると新しい Python オブジェクトがその度に
作られます。


可変サイズのデータ型
--------------------

"ctypes" は、可変サイズの配列や構造体をある程度サポートしています。

"resize()" 関数は既存の ctypes オブジェクトのメモリバッファのサイズを
変更したい場合に使えます。この関数は第一引数にオブジェクト、第二引数に
要求されたサイズをバイト単位で指定します。メモリブロックはオブジェクト
型で指定される通常のメモリブロックより小さくすることはできません。これ
をやろうとすると、 "ValueError" が送出されます。:

   >>> short_array = (c_short * 4)()
   >>> print(sizeof(short_array))
   8
   >>> resize(short_array, 4)
   Traceback (most recent call last):
       ...
   ValueError: minimum size is 8
   >>> resize(short_array, 32)
   >>> sizeof(short_array)
   32
   >>> sizeof(type(short_array))
   8
   >>>

これはこれで上手くいっていますが、この配列の追加した要素へどうやってア
クセスするのでしょうか? この型は要素の数が 4 個であるとまだ認識してい
るので、他の要素にアクセスするとエラーになります。:

   >>> short_array[:]
   [0, 0, 0, 0]
   >>> short_array[7]
   Traceback (most recent call last):
       ...
   IndexError: invalid index
   >>>

"ctypes" で可変サイズのデータ型を使うもう 1 つの方法は、Python の動的
な性質を利用し、必要なサイズがわかった後で、場合に応じてデータ型を定義
または再定義することです。


ctypesリファレンス
==================


共有ライブラリをロードする
--------------------------

共有ライブラリを Python プロセスにロードする方法はいくつかあります。
その 1 つは、"CDLL" またはそのサブクラスのインスタンスを作成する方法で
す:

class ctypes.CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False, winmode=None)

   ロード済みの共有ライブラリを表します。

   このライブラリの関数は標準の C 呼び出し規約を使用し、int を返すと仮
   定されます。 これらのライブラリがエクスポートする関数を呼び出す前に
   、Python の *global interpreter lock* を解放し、呼び出し後に再取得
   します。 関数の動作を変えるには、サブクラス "OleDLL"、"WinDLL"、
   "PyDLL" を使用してください。

   すでにロードした共有ライブラリの "ハンドル" がある場合、それを
   *handle* 引数に渡すと、開いているライブラリを新しい "CDLL" オブジェ
   クトでラップできます。 この場合、*name* は "_name" 属性の設定にのみ
   使われますが、調整や検証が行われることもあります。

   *handle* が "None" の場合、プラットフォームの *dlopen(3)* または
   LoadLibraryExW 関数を使って、ライブラリをプロセスにロードし、そのハ
   ンドルを取得します。

   *name* は開く共有ライブラリのパス名です。 *name* にパスの区切り文字
   が含まれない場合、プラットフォーム固有の方法でライブラリを探します
   。

   Windows では、".DLL" 接尾辞を省略できます (詳細は LoadLibraryExW の
   ドキュメントを参照してください)。 ほかのプラットフォーム固有の接頭
   辞や接尾辞 ("lib"、".so"、".dylib"、バージョン番号など) は *name*
   に含める必要があり、自動的には追加されません。 詳しくは 共有ライブ
   ラリを見つける を参照してください。

   Windows 以外では、*name* に "None" を指定できます。 この場合、
   "dlopen()" を "NULL" を指定して呼び出し、メインプログラムを「ライブ
   ラリ」として開きます。 *name* が空の場合に同じ動作をするシステムも
   ありますが、"None" / "NULL" の方が移植性に優れています。

   CPython の実装の詳細: CPython は "libc" にリンクされるため、C 標準
   ライブラリへのアクセスには *name* に "None" を指定する方法がよく使
   われます。

      >>> printf = ctypes.CDLL(None).printf
      >>> printf.argtypes = [ctypes.c_char_p]
      >>> printf(b"hello\n")
      hello
      6

   Python C API にアクセスする場合は、各プラットフォームで動作する
   "ctypes.pythonapi" を優先してください。

   *mode* パラメータを使うと、ライブラリをどのようにロードするかを指定
   できます。 詳細は *dlopen(3)* マニュアルページを参考にしてください
   。 Windows では *mode* は無視されます。 POSIX システムでは RTLD_NOW
   が常に追加され、設定変更はできません。

   *use_errno* 引数を真に設定すると、システムのエラー番号 "errno" に安
   全にアクセスする ctypes の仕組みが有効になります。 "ctypes" は、シ
   ステムの "errno" 変数のコピーをスレッドローカルに保持します。
   "use_errno=True" で作成した外部関数を呼び出すと、呼び出し前の
   "errno" 値を ctypes 内部のコピーと交換し、呼び出し直後にも同じ交換
   を行います。 この仕組みは、インタープリタ自体と同じ C ランタイムラ
   イブラリを使うライブラリに対してのみ機能します。 別の C ランタイム
   (例えば Windows 上の別の CRT) にリンクされたライブラリは、独自の
   "errno" を持ち、"ctypes" からは参照できません。

   "ctypes.get_errno()" 関数は ctypes のプライベートコピーの値を返しま
   す。そして、 "ctypes.set_errno()" 関数は ctypes のプライベートコピ
   ーを置き換え、以前の値を返します。

   *use_last_error* 引数を真に設定すると、Windows API 関数の
   "GetLastError()" と "SetLastError()" が管理する Windows エラーコー
   ドについて同じ仕組みが有効になります。 ctypes 内部にある Windows エ
   ラーコードのコピーの取得と変更には、"ctypes.get_last_error()" と
   "ctypes.set_last_error()" を使います。

   Windows では *mode* が無視されるため、*winmode* 引数でライブラリの
   ロード方法を指定します。 Win32 API の LoadLibraryExW の flags 引数
   として有効な値を指定できます。 省略時には、DLL ハイジャックなどの問
   題を避けるため、最も安全に DLL をロードするフラグが使われます。 正
   しいライブラリと依存ライブラリがロードされることを確実にする最も安
   全な方法は、DLL のフルパスを渡すことです。

   Windows では、DLL の名前が存在していても "CDLL" インスタンスの作成
   が失敗することがあります。 ロードする DLL の依存先 DLL が見つからな
   い場合、*"[WinError 126] The specified module could not be found"*
   というメッセージで "OSError" が送出されます。 Windows API がこの情
   報を返さないため、エラーメッセージには見つからない DLL の名前が含ま
   れず、原因の特定が難しくなります。 このエラーを解決し、見つからない
   DLL を特定するには、依存先 DLL の一覧を調べ、Windows のデバッグツー
   ルやトレースツールで、どれが見つからないのかを判定する必要がありま
   す。

   参考: Microsoft の DUMPBIN ツール -- 依存先 DLL を調べるツールです。

   バージョン 3.8 で変更: *winmode* 引数が追加されました。

   バージョン 3.12 で変更: *name* 引数に *path-like object* を指定でき
   るようになりました。

   このクラスのインスタンスには公開メソッドがありません。 共有ライブラ
   リがエクスポートする関数には、属性やインデックスを使ってアクセスで
   きます。 属性を通じてアクセスすると結果がキャッシュされ、繰り返しア
   クセスしても毎回同じオブジェクトを返します。 一方、インデックスを通
   じてアクセスすると、毎回新しいオブジェクトを返します。

      >>> from ctypes import CDLL
      >>> libc = CDLL("libc.so.6")  # Linux の場合
      >>> libc.time == libc.time
      True
      >>> libc['time'] == libc['time']
      False

   以下の公開属性を利用できます。 エクスポートされた関数名と衝突しない
   よう、名前はアンダースコアで始まります:

   _handle

      ライブラリへのアクセスに用いられるシステムハンドル。

   _name

      コンストラクタに渡されたライブラリの名前。

class ctypes.OleDLL

   共通の情報については、スーパークラス "CDLL" を参照してください。

   このライブラリの関数は "stdcall" 呼び出し規約を使用し、Windows 固有
   の "HRESULT" コードを返すと仮定されます。 "HRESULT" の値には、関数
   呼び出しの成功または失敗を示す情報と、追加のエラーコードが含まれま
   す。 戻り値が失敗を示す場合、"OSError" を自動的に送出します。

   利用可能な環境: Windows

   バージョン 3.3 で変更: 以前は "WindowsError" を送出していましたが、
   現在は "OSError" の別名になっています。

class ctypes.WinDLL

   共通の情報については、スーパークラス "CDLL" を参照してください。

   これらのライブラリの関数は "stdcall" 呼び出し規約を使用し、デフォル
   トでは int を返すと仮定されます。

   利用可能な環境: Windows

class ctypes.PyDLL

   共通の情報については、スーパークラス "CDLL" を参照してください。

   このライブラリの関数を呼び出す場合、呼び出し中に Python の GIL は解
   放 *されず*、関数の実行後に Python のエラーフラグを検査します。 エ
   ラーフラグが設定されている場合は、Python の例外を送出します。

   したがって、これは Python C API 関数を直接呼び出す場合にのみ役立ち
   ます。

ctypes.RTLD_GLOBAL

   *mode* パラメータとして使うフラグ。このフラグが利用できないプラット
   フォームでは、整数のゼロと定義されています。

ctypes.RTLD_LOCAL

   *mode* パラメータとして使うフラグ。これが利用できないプラットフォー
   ムでは、 *RTLD_GLOBAL* と同様です。

ctypes.DEFAULT_MODE

   共有ライブラリをロードするために使われるデフォルトモード。 OSX 10.3
   では *RTLD_GLOBAL* であり、そうでなければ *RTLD_LOCAL* と同じです。

あらかじめ作成されている "LibraryLoader" クラスのインスタンスを使って
、共有ライブラリをロードすることもできます。 "LoadLibrary()" メソッド
を呼び出すか、ローダーインスタンスの属性としてライブラリを取得します。

class ctypes.LibraryLoader(dlltype)

   共有ライブラリをロードするクラス。 *dlltype* は "CDLL" 、 "PyDLL"
   、 "WinDLL" もしくは "OleDLL" 型の一つであるべきです。

   "__getattr__()" には特別な動作があります。 ライブラリローダーインス
   タンスの属性にアクセスすると、共有ライブラリをロードできます。 結果
   はキャッシュされるため、属性へのアクセスを繰り返しても毎回同じライ
   ブラリを返します。

   LoadLibrary(name)

      共有ライブラリをプロセスへロードし、それを返します。このメソッド
      はライブラリの新しいインスタンスを常に返します。

これらの前もって作られたライブラリローダーを利用することができます。:

   ctypes.cdll

      "CDLL" インスタンスを作ります。

   ctypes.windll

      "WinDLL" インスタンスを作成します。

      利用可能な環境: Windows

   ctypes.oledll

      "OleDLL" インスタンスを作成します。

      利用可能な環境: Windows

   ctypes.pydll

      "PyDLL" インスタンスを作ります。

   ctypes.pythonapi

      Python C API 関数を属性として公開する "PyDLL" のインスタンスです
      。 すべての関数が C の int を返すと仮定していますが、実際には常
      にそうとは限りません。 これらの関数を使うには、"restype" 属性に
      正しい型を設定する必要があります。

      注釈:

        Python インタープリタが静的にリンクされている場合、これは
        "None" になることがあります。

これらのオブジェクトを通じてライブラリをロードすると、ロードに使うライ
ブラリ名を文字列引数 "name" とする 監査イベント "ctypes.dlopen" が発生
します。

ロード済みライブラリの関数にアクセスすると、引数 "library" (ライブラリ
オブジェクト) と "name" (文字列または整数のシンボル名) を持つ監査イベ
ント "ctypes.dlsym" が発生します。

ライブラリオブジェクトではなくハンドルだけが利用できる場合、関数にアク
セスすると、引数 "handle" (生のライブラリハンドル) と "name" を持つ監
査イベント "ctypes.dlsym/handle" が発生します。


共有ライブラリを見つける
------------------------

コンパイル型の言語でプログラミングする場合、共有ライブラリには、プログ
ラムのコンパイルやリンクの際と、プログラムの実行時にアクセスします。
プログラマーが短い名前を指定すると、C コンパイラ、リンカー、実行時の動
的ライブラリローダーがシステム固有の方法で連携し、ロードするライブラリ
のファイル名を探します。

短い名前とファイル名の対応は、プラットフォーム間で一貫した形では公開さ
れていませんが、"ctypes.util" モジュールは、その対応を求めようとする
"find_library()" 関数を提供します。 ただし、後方互換性の問題から新しい
プラットフォームや設定に合わせて動作を調整するのは難しいため、この関数
は *soft deprecated* です。

"ctypes" で共有ライブラリをラップする場合、実行時に "find_library()"
で探す代わりに、開発時に共有ライブラリ名を決めてラッパーモジュールに直
接記述することを検討してください。 また、利用するライブラリをユーザー
が選べる設定オプションや環境変数を追加し、"find_library()" はデフォル
トや代替手段として使うことも検討してください。

ctypes.util.find_library(name)

   ライブラリを探し、そのパス名を返します。

   *name* は、"lib" などの接頭辞や、".so"、".dylib"、バージョン番号な
   どの接尾辞を含まない、ライブラリの「短い」名前です (POSIX リンカー
   の "-l" オプションで使う形式です)。 結果は "CDLL" に渡せる形式にな
   ります。

   ライブラリが見つからない場合は "None" を返します。

   厳密な動作はシステムに依存し、Python のために、または Python が使用
   するコンパイラ、リンカー、ローダーの動作と一致する *保証はありませ
   ん*。 この関数はデフォルトや代替手段としてのみ使うことを推奨します
   。

   バージョン 3.15 で ソフト非推奨 <Soft deprecated>: この関数は、現在
   動作する環境での使用のために維持されますが、追加のプラットフォーム
   や設定に対応する更新は予定されていません。

Linux では、"find_library()" は外部プログラム ("/sbin/ldconfig"、"gcc"
、"objdump"、"ld") を実行してライブラリファイルを探そうとします。 これ
らのプログラムの出力が Python の使う動的リンカーに対応していない場合、
この関数の結果は誤解を招くことがあります。

バージョン 3.6 で変更: Linux では、ライブラリを検索する際に、他の方法
でライブラリが見つけられない場合は、 "LD_LIBRARY_PATH" 環境変数の値が
使われます

ここに例があります:

   >>> from ctypes.util import find_library
   >>> find_library("m")
   'libm.so.6'
   >>> find_library("c")
   'libc.so.6'
   >>> find_library("bz2")
   'libbz2.so.1.0'
   >>>

macOS と Android では、"find_library()" はシステム標準の命名規則とパス
を使ってライブラリを探し、成功するとフルパス名を返します。

   >>> from ctypes.util import find_library
   >>> find_library("c")
   '/usr/lib/libc.dylib'
   >>> find_library("m")
   '/usr/lib/libm.dylib'
   >>> find_library("bz2")
   '/usr/lib/libbz2.dylib'
   >>> find_library("AGL")
   '/System/Library/Frameworks/AGL.framework/AGL'
   >>>

Windows では、"find_library()" はシステムの検索パスに沿って探し、フル
パス名を返します。 ただし、定義済みの命名規則がないため、
"find_library("c")" のような呼び出しは失敗して "None" を返します。

ctypes.util.find_msvcrt()

   Python と拡張モジュールが使用する VC ランタイムライブラリのファイル
   名を返します。

   ライブラリ名を判定できない場合は "None" を返します。 特に、最近のバ
   ージョンの VC ランタイムライブラリは直接ロードできないため、この結
   果になります。

   もし、例えば拡張モジュールにより割り付けられたメモリを "free(void
   *)" で解放する必要があるなら、メモリ割り付けを行ったのと同じライブ
   ラリの関数を使うことが重要です。

   利用可能な環境: Windows


ロード済み共有ライブラリの一覧取得
----------------------------------

共有ライブラリからロードしたコードに依存するコードを書く場合、現在のプ
ロセスにどの共有ライブラリがすでにロードされているかを知ると役立つこと
があります。

"ctypes.util" モジュールの "dllist()" 関数は、各プラットフォームが提供
する異なる API を呼び出して、現在のプロセスにすでにロードされた共有ラ
イブラリを調べます。

この関数の具体的な出力はシステムに依存します。 ほとんどのプラットフォ
ームでは、リストの最初の要素は現在のプロセス自体を表し、空文字列の場合
もあります。 例えば、glibc を使う Linux では次のような結果を返すことが
あります。

   >>> from ctypes.util import dllist
   >>> dllist()
   ['', 'linux-vdso.so.1', '/lib/x86_64-linux-gnu/libm.so.6', '/lib/x86_64-linux-gnu/libc.so.6', ... ]


外部関数
--------

前の節で説明したとおり、外部関数にはロード済み共有ライブラリの属性とし
てアクセスできます。 この方法で作成した関数オブジェクトは、デフォルト
で任意の数の引数を受け付け、任意の ctypes データインスタンスを引数に取
ります。 戻り値の型は、ライブラリローダーが指定するデフォルトの型にな
ります。

これらは、非公開の "_CFuncPtr" クラスを継承する、非公開のローカルクラ
ス "_FuncPtr" のインスタンスです ("ctypes" では公開されていません)。

   >>> import ctypes
   >>> lib = ctypes.CDLL(None)
   >>> issubclass(lib._FuncPtr, ctypes._CFuncPtr)
   True
   >>> lib._FuncPtr is ctypes._CFuncPtr
   False

class ctypes._CFuncPtr

   C の呼び出し可能外部関数のためのベースクラス。

   外部関数のインスタンスも C 互換データ型です。それらは C の関数ポイ
   ンタを表しています。

   この振る舞いは外部関数オブジェクトの特別な属性に代入することによっ
   て、カスタマイズすることができます。

   restype

      外部関数の結果の型を指定するために ctypes 型を代入する。何も返さ
      ない関数を表す void に対しては "None" を使います。

      ctypes の型以外の、Python の呼び出し可能オブジェクトを代入するこ
      ともできます。 この場合、関数は C の int を返すと仮定され、その
      整数を渡して呼び出し可能オブジェクトを呼び出すことで、追加の処理
      やエラー検査を行えます。 この使い方は非推奨です。 より柔軟な後処
      理やエラー検査を行うには、"restype" に ctypes のデータ型を設定し
      、"errcheck" 属性に呼び出し可能オブジェクトを代入してください。

   argtypes

      関数が受け取る引数の型を指定するには、ctypes の型のタプルを代入
      します。 タプルの長さより少ない引数で関数を呼び出すと、
      "TypeError" を送出します。 "stdcall" 呼び出し規約を使う関数は、
      引数が多すぎる場合にも "TypeError" を送出します。 "cdecl" 呼び出
      し規約を使う関数は、指定していない追加の引数も受け付けます。

      When a foreign function is called, each actual argument is
      passed to the "from_param()" class method of the items in the
      "argtypes" tuple, this method allows adapting the actual
      argument to an object that the foreign function accepts.  For
      example, a "c_char_p" item in the "argtypes" tuple will convert
      a string passed as argument into a bytes object using ctypes
      conversion rules.

      新機能: "argtypes" に ctypes の型以外の要素も指定できるようにな
      りました。 ただし、各要素には、引数として使える値 (整数、文字列
      、ctypes インスタンス) を返す "from_param()" メソッドが必要です
      。 これにより、独自のオブジェクトを関数の引数に適合させるアダプ
      ターを定義できます。

   errcheck

      Python 関数または他の呼び出し可能オブジェクトをこの属性に代入し
      ます。呼び出し可能オブジェクトは三つ以上の引数とともに呼び出され
      ます。

      callable(result, func, arguments)

         *result* は、"restype" 属性で指定された型で外部関数が返す値で
         す。

         *func* は外部関数オブジェクト自身で、これにより複数の関数の処
         理結果をチェックまたは後処理するために、同じ呼び出し可能オブ
         ジェクトを再利用できるようになります。

         *arguments* は、関数呼び出しに渡された引数を含むタプルです。
         "ctypes" がその呼び出しのために作成した出力引数も含みます。
         これにより、使われた引数に応じて動作を調整できます。

      呼び出し可能オブジェクトが受け取った *arguments* タプルを変更せ
      ずに返すと、"ctypes" は出力引数の返却を含む通常の結果処理を続け
      ます (関数プロトタイプ を参照)。 ほかのオブジェクトを返した場合
      は、そのオブジェクトが外部関数呼び出しの戻り値になります。 また
      、結果の値を検査し、外部関数呼び出しが失敗した場合に例外を送出す
      ることもできます。

      例えば、次の呼び出し可能オブジェクトは、外部関数が負の戻り値で失
      敗を示した場合に例外を送出し、それ以外の場合は "ctypes" に結果の
      処理を任せます。

         def errcheck(result, func, arguments):
             if result < 0:
                 raise RuntimeError(f"call failed with error {result}")
             return arguments

      次の例は、ブール値として使われる C の "int" を "bool" に変換して
      、結果を置き換えます。

         def errcheck(result, func, arguments):
             return result != 0

Windows では、外部関数呼び出しがアクセス違反などのシステム例外を発生さ
せると、それを捕捉して適切な Python 例外に置き換えます。 さらに、引数
"code" を持つ監査イベント "ctypes.set_exception" が発生し、監査フック
が独自の例外に置き換えられるようになります。

外部関数の呼び出し方によっては、またこのモジュールの一部の関数では、引
数 "function pointer" と "arguments" を持つ監査イベント
"ctypes.call_function" が発生する場合があります。


関数プロトタイプ
----------------

外部関数は関数プロトタイプをインスタンス化することによって作成されます
。 関数プロトタイプは C の関数プロトタイプと似ています。実装は定義せず
に、関数 (返り値の型、引数の型、呼び出し規約) を記述します。 ファクト
リ関数は、その関数に要求される返り値の型と引数の型とともに呼び出されま
す。そしてこの関数はデコレータファクトリとしても使え、 "@wrapper" 構文
で他の関数に適用できます。 例については コールバック関数 を参照してく
ださい。

ctypes.CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)

   返された関数プロトタイプは標準 C 呼び出し規約をつかう関数を作成しま
   す。関数は呼び出されている間 GIL を解放します。 *use_errno* が真に
   設定されれば、呼び出しの前後で System 変数 "errno" の ctypesプライ
   ベートコピーは本当の "errno" の値と交換されます。 *use_last_error*
   も Windows エラーコードに対するのと同様です。

ctypes.WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)

   返された関数プロトタイプは、"stdcall" 呼び出し規約を使う関数を作成
   します。 関数は呼び出し中に GIL を解放します。 *use_errno* と
   *use_last_error* の意味は上記と同じです。

   利用可能な環境: Windows

ctypes.PYFUNCTYPE(restype, *argtypes)

   返された関数プロトタイプは、Python 呼び出し規約を使う関数を作成しま
   す。 "CFUNCTYPE()" や "WINFUNCTYPE()" と異なり、ctypes は外部関数を
   呼び出す前に GIL を解放 *しない* ので、その関数は Python C API を安
   全に使用できます。 ただし、呼び出し *中* の GIL の解放を防ぐもので
   はありません。

ファクトリ関数によって作られた関数プロトタイプは呼び出しのパラメータの
型と数に依存した別の方法でインスタンス化することができます。 :

prototype(address)

   指定されたアドレス(整数でなくてはなりません)の外部関数を返します。

prototype(callable)

   Python の *callable* から C の呼び出し可能関数(コールバック関数) を
   作成します。

prototype(func_spec[, paramflags])

   共有ライブラリがエクスポートしている外部関数を返します。
   *func_spec* は 2 要素タプル "(name_or_ordinal, library)" でなければ
   なりません。第一要素はエクスポートされた関数の名前である文字列、ま
   たはエクスポートされた関数の序数である小さい整数です。第二要素は共
   有ライブラリインスタンスです。

prototype(vtbl_index, name[, paramflags[, iid]])

   COM メソッドを呼び出す外部関数を返します。 *vtbl_index* は仮想関数
   テーブルのインデックスで、非負の小さい整数です。 *name* は COM メソ
   ッドの名前です。 *iid* はオプションのインターフェイス識別子へのポイ
   ンタで、拡張されたエラー情報の提供のために使われます。

   *iid* を指定しない場合、COM メソッドの呼び出しが失敗すると
   "OSError" を送出します。 *iid* を指定した場合は、代わりに
   "COMError" を送出します。

   COM メソッドは特別な呼び出し規約を使います。 "argtypes" タプルで指
   定した引数に加えて、第 1 引数として COM インターフェースへのポイン
   タが必要です。

   利用可能な環境: Windows

オプションの *paramflags* パラメータは上述した機能より多機能な外部関数
ラッパーを作成します。

*paramflags* は、"argtypes" と同じ長さのタプルでなければなりません。

このタプルの個々の要素はパラメータについてのより詳細な情報を持ち、 1
、 2 もしくは 3 要素を含むタプルでなければなりません。

第一要素はパラメータについてのフラグの組み合わせを含んだ整数です。

   1
      入力パラメータを関数に指定します。

   2
      出力パラメータ。外部関数が値を書き込みます。

   4
      デフォルトで整数ゼロになる入力パラメータ。

オプションの第二要素はパラメータ名の文字列です。これが指定された場合は
、外部関数を名前付きパラメータで呼び出すことができます。

オプションの第三要素はこのパラメータのデフォルト値です。

次の例では、Windows の "MessageBoxW" 関数をラップして、引数のデフォル
ト値と名前付き引数をサポートする方法を示します。 Windows ヘッダーファ
イルの C 宣言は次のとおりです。

   WINUSERAPI int WINAPI
   MessageBoxW(
       HWND hWnd,
       LPCWSTR lpText,
       LPCWSTR lpCaption,
       UINT uType);

"ctypes" を使ったラップは次のようになります。

   >>> from ctypes import c_int, WINFUNCTYPE, windll
   >>> from ctypes.wintypes import HWND, LPCWSTR, UINT
   >>> prototype = WINFUNCTYPE(c_int, HWND, LPCWSTR, LPCWSTR, UINT)
   >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", "Hello from ctypes"), (1, "flags", 0)
   >>> MessageBox = prototype(("MessageBoxW", windll.user32), paramflags)

これで外部関数の "MessageBox" を次のような方法で呼び出すことができるよ
うになりました:

   >>> MessageBox()
   >>> MessageBox(text="Spam, spam, spam")
   >>> MessageBox(flags=2, text="foo bar")

二番目の例は出力パラメータについて説明します。 win32 の
"GetWindowRect" 関数は、指定されたウィンドウの大きさを呼び出し側が与え
る "RECT" 構造体へコピーすることで取り出します。 C の宣言はこうです。:

   WINUSERAPI BOOL WINAPI
   GetWindowRect(
        HWND hWnd,
        LPRECT lpRect);

"ctypes" を使ったラップは次のようになります。

   >>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
   >>> from ctypes.wintypes import BOOL, HWND, RECT
   >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
   >>> paramflags = (1, "hwnd"), (2, "lprect")
   >>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
   >>>

出力パラメータを持つ関数は、単一のパラメータがある場合にはその出力パラ
メータ値を、複数のパラメータがある場合には出力パラメータ値が入ったタプ
ルを、それぞれ自動的に返します。そのため、GetWindowRect 関数は呼び出さ
れると RECT インスタンスを返します。

出力引数は "errcheck" プロトコルと組み合わせて、出力の追加処理やエラー
検査を行えます。 win32 API の "GetWindowRect" 関数は成功か失敗かを
"BOOL" で返すので、次の関数でエラーを検査し、API 呼び出しが失敗した場
合に例外を送出できます。

   >>> def errcheck(result, func, args):
   ...     if not result:
   ...         raise WinError()
   ...     return args
   ...
   >>> GetWindowRect.errcheck = errcheck
   >>>

"errcheck" 関数が受け取った引数タプルをそのまま返すと、"ctypes" は出力
引数に対する通常の処理を続けます。 "RECT" インスタンスの代わりにウィン
ドウ座標のタプルを返したい場合は、関数内でフィールドを取得してそれらを
返せます。 この場合、通常の処理は行われなくなります。

   >>> def errcheck(result, func, args):
   ...     if not result:
   ...         raise WinError()
   ...     rc = args[1]
   ...     return rc.left, rc.top, rc.bottom, rc.right
   ...
   >>> GetWindowRect.errcheck = errcheck
   >>>


ユーティリティー関数
--------------------

ctypes.addressof(obj)

   メモリバッファのアドレスを示す整数を返します。 *obj* は ctypes 型の
   インスタンスでなければなりません。

   引数 "obj" を指定して 監査イベント "ctypes.addressof" を送出します
   。

ctypes.alignment(obj_or_type)

   ctypes 型のアライメントの必要条件を返します。 *obj_or_type* は
   ctypes 型またはインスタンスでなければなりません。

ctypes.byref(obj[, offset])

   *obj* (ctypes 型のインスタンスでなければならない) への軽量ポインタ
   を返します。 *offset* はデフォルトでは 0 で、内部ポインターへ加算さ
   れる整数です。

   "byref(obj, offset)" は、 C コードとしては、以下のようにみなされま
   す。:

      (((char *)&obj) + offset)

   返されるオブジェクトは外部関数呼び出しのパラメータとしてのみ使用で
   きます。"pointer(obj)" と似たふるまいをしますが、作成が非常に速く行
   えます。

ctypes.CopyComPointer(src, dst)

   COM ポインタを *src* から *dst* にコピーし、Windows 固有の
   "HRESULT" 値を返します。

   *src* が "NULL" でない場合、その "AddRef" メソッドを呼び出して参照
   カウントを増やします。

   一方、新しい値を代入する前に *dst* の参照カウントを減らすことはあり
   ません。 *dst* が "NULL" でなければ、呼び出し側が必要に応じてその
   "Release" メソッドを呼び出し、参照カウントを減らす責任を持ちます。

   利用可能な環境: Windows

   Added in version 3.14.

ctypes.cast(obj, type)

   この関数は C のキャスト演算子に似ています。*obj* と同じメモリブロッ
   クを指している *type* の新しいインスタンスを返します。*type* はポイ
   ンタ型でなければならず、*obj* はポインタとして解釈できるオブジェク
   トでなければなりません。

ctypes.create_string_buffer(init, size=None)
ctypes.create_string_buffer(size)

   この関数は変更可能な文字バッファを作成します。返されるオブジェクト
   は "c_char" の ctypes 配列です。

   *size* を指定する場合 ("None" 以外の場合)、"int" でなければなりませ
   ん。 返す配列のサイズを指定します。

   *init* 引数を指定する場合、"bytes" でなければなりません。 配列の要
   素の初期化に使います。 この方法で初期化されないバイトは、ゼロ (NUL)
   に設定されます。

   *size* を省略した場合 (または "None" の場合)、バッファを *init* よ
   り 1 要素分大きくすることで、実質的に NUL 終端文字を追加します。

   両方の引数を指定する場合、*size* は "len(init)" 以上でなければなり
   ません。

   警告:

     *size* が "len(init)" と等しい場合、NUL 終端文字は追加されません
     。 そのようなバッファを C 文字列として扱わないでください。

   例えば:

      >>> bytes(create_string_buffer(2))
      b'\x00\x00'
      >>> bytes(create_string_buffer(b'ab'))
      b'ab\x00'
      >>> bytes(create_string_buffer(b'ab', 2))
      b'ab'
      >>> bytes(create_string_buffer(b'ab', 4))
      b'ab\x00\x00'
      >>> bytes(create_string_buffer(b'abcdef', 2))
      Traceback (most recent call last):
         ...
      ValueError: byte string too long

   引数 "init", "size" を指定して 監査イベント
   "ctypes.create_string_buffer" を送出します。

ctypes.create_unicode_buffer(init, size=None)
ctypes.create_unicode_buffer(size)

   この関数は変更可能な Unicode 文字バッファを作成します。返されるオブ
   ジェクトは "c_wchar" の ctypes 配列です。

   この関数は "create_string_buffer()" と同じ引数を取りますが、*init*
   は文字列である必要があり、*size* は "c_wchar" の個数を表します。

   引数 "init", "size" を指定して 監査イベント
   "ctypes.create_unicode_buffer" を送出します。

ctypes.DllCanUnloadNow()

   この関数は、ctypes でプロセス内 COM サーバーを実装するためのフック
   です。 "_ctypes" 拡張 DLL がエクスポートする "DllCanUnloadNow()" 関
   数から呼び出されます。

   利用可能な環境: Windows

ctypes.DllGetClassObject()

   この関数は、ctypes でプロセス内 COM サーバーを実装するためのフック
   です。 "_ctypes" 拡張 DLL がエクスポートする "DllGetClassObject()"
   関数から呼び出されます。

   利用可能な環境: Windows

ctypes.util.dllist()

   現在のプロセスにロードされた共有ライブラリのパスの一覧を取得しよう
   とします。 これらのパスには正規化などの処理は一切行いません。 基盤
   となるプラットフォーム API が失敗した場合、"OSError" を送出すること
   があります。 厳密な動作はシステムに依存します。

   ほとんどのプラットフォームでは、リストの最初の要素は現在の実行ファ
   イルを表します。 空文字列の場合もあります。

   利用可能な環境: Windows, macOS, iOS, glibc, BSD libc, musl

   Added in version 3.14.

ctypes.FormatError([code])

   エラーコード *code* の説明文を返します。 エラーコードを指定しない場
   合は、Windows API 関数 "GetLastError()" を呼び出して最後のエラーコ
   ードを取得し、それを使用します。

   利用可能な環境: Windows

ctypes.GetLastError()

   呼び出し元スレッドで Windows が設定した最後のエラーコードを返します
   。 Windows の "GetLastError()" 関数を直接呼び出し、ctypes 内部のエ
   ラーコードのコピーは返しません。

   利用可能な環境: Windows

ctypes.get_errno()

   システムの "errno" 変数の、スレッドローカルなプライベートコピーを返
   します。

   引数無しで 監査イベント "ctypes.get_errno" を送出します。

ctypes.get_last_error()

   呼び出し元スレッドにある、システムの "LastError" 変数の ctypes 内部
   のコピーの現在値を返します。

   利用可能な環境: Windows

   引数無しで 監査イベント "ctypes.get_last_error" を送出します。

ctypes.memmove(dst, src, count)

   標準 C の memmove ライブラリ関数と同じものです。: *count* バイトを
   *src* から *dst* へコピーします。 *dst* と *src* はポインタへ変換可
   能な整数または ctypes インスタンスでなければなりません。

ctypes.memset(dst, c, count)

   標準 C の memset ライブラリ関数と同じものです。: アドレス *dst* の
   メモリブロックを値 *c* を *count* バイト分書き込みます。 *dst* はア
   ドレスを指定する整数または ctypes インスタンスである必要があります
   。

ctypes.POINTER(type, /)

   ctypes のポインタ型を作成するか、既存の型を返します。 ポインタ型は
   内部でキャッシュされて再利用されるため、繰り返し呼び出しても負荷は
   小さくなります。 *type* は ctypes の型でなければなりません。

   結果のポインタ型は、*type* の "__pointer_type__" 属性にキャッシュさ
   れます。 最初に "POINTER" を呼び出す前にこの属性を設定すれば、独自
   のポインタ型を指定できます。 ただし、この方法は推奨しません。 将来
   の Python バージョンで変わりうる実装の詳細に依存せず、適切なポイン
   タ型を手動で作成することは難しいためです。

ctypes.pointer(obj, /)

   *obj* を指す新しいポインタインスタンスを作成します。 返されるオブジ
   ェクトの型は "POINTER(type(obj))" です。

   注意: 外部関数呼び出しへオブジェクトへのポインタを渡したいだけなら
   、はるかに高速な "byref(obj)" を使うべきです。

ctypes.resize(obj, size)

   この関数は *obj* の内部メモリバッファのサイズを変更します。 *obj*
   は ctypes 型のインスタンスでなければなりません。バッファを
   "sizeof(type(obj))" で与えられるオブジェクト型の本来のサイズより小
   さくすることはできませんが、バッファを拡大することはできます。

ctypes.set_errno(value)

   システム変数 "errno" の、呼び出し元スレッドでの ctypes のプライベー
   トコピーの現在値を *value* に設定し、前の値を返します。

   引数 "errno" を指定して 監査イベント "ctypes.set_errno" を送出しま
   す。

ctypes.set_last_error(value)

   呼び出し元スレッドにある、システムの "LastError" 変数の ctypes 内部
   のコピーの現在値を *value* に設定し、以前の値を返します。

   利用可能な環境: Windows

   引数 "error" を指定して 監査イベント "ctypes.set_last_error" を送出
   します。

ctypes.sizeof(obj_or_type)

   ctypes の型やインスタンスのメモリバッファのサイズをバイト数で返しま
   す。C の "sizeof" 演算子と同様の動きをします。

ctypes.string_at(ptr, size=-1)

   *void *ptr* にあるバイト文字列を返します。 *size* を指定した場合は
   そのサイズを使い、省略した場合はゼロ終端文字列と仮定します。

   引数 "ptr"、"size" を持つ 監査イベント "ctypes.string_at" が発生し
   ます。

ctypes.WinError(code=None, descr=None)

   "OSError" のインスタンスを作成します。 *code* を指定しない場合は、
   "GetLastError()" を呼び出してエラーコードを取得します。 *descr* を
   指定しない場合は、"FormatError()" を呼び出してエラーの説明文を取得
   します。

   利用可能な環境: Windows

   バージョン 3.3 で変更: 以前は "WindowsError" のインスタンスを作成し
   ていましたが、現在は "OSError" の別名になっています。

ctypes.wstring_at(ptr, size=-1)

   *void *ptr* にあるワイド文字列を返します。 *size* を指定した場合は
   文字数として使い、省略した場合はゼロ終端文字列と仮定します。

   引数 "ptr"、"size" を持つ 監査イベント "ctypes.wstring_at" が発生し
   ます。

ctypes.memoryview_at(ptr, size, readonly=False)

   *void *ptr* から始まるメモリを参照する、長さ *size* の "memoryview"
   オブジェクトを返します。

   *readonly* が真の場合、返される "memoryview" オブジェクトを使って参
   照先のメモリを変更することはできません (ほかの方法で行った変更は、
   返されたオブジェクトにも反映されます)。

   この関数は "string_at()" に似ていますが、指定したメモリのコピーを作
   成しない点が大きく異なります。 "memoryview((c_byte *
   size).from_address(ptr))" と意味的に同等で、より効率的な代替手段で
   す。 "from_address()" は整数のみを受け付けますが、*ptr* には
   "ctypes.POINTER" や "byref()" のオブジェクトも指定できます。

   引数 "address"、"size"、"readonly" を持つ 監査イベント
   "ctypes.memoryview_at" が発生します。

   Added in version 3.14.


データ型
--------

class ctypes._CData

   この非公開クラスはすべての ctypes データ型の共通のベースクラスです
   。他のことはさておき、すべての ctypes 型インスタンスは C 互換データ
   を保持するメモリブロックを内部に持ちます。このメモリブロックのアド
   レスは "addressof()" ヘルパー関数が返します。別のインスタンス変数が
   "_objects" として公開されます。これはメモリブロックがポインタを含む
   場合に存続し続ける必要のある他の Python オブジェクトを含んでいます
   。

   ctypes データ型に共通のメソッドです。 すべてクラスメソッドです (正
   確には *メタクラス* のメソッドです):

   from_buffer(source[, offset])

      このメソッドは *source* オブジェクトのバッファを共有する ctypes
      のインスタンスを返します。 *source* オブジェクトは書き込み可能バ
      ッファインターフェースをサポートしている必要があります。オプショ
      ンの *offset* 引数では *source* バッファのオフセットをバイト単位
      で指定します。デフォルトではゼロです。もし *source* バッファが十
      分に大きくなければ、 "ValueError" が送出されます。

      引数 "pointer", "size", "offset" を指定して 監査イベント
      "ctypes.cdata/buffer" を送出します。

   from_buffer_copy(source[, offset])

      このメソッドは *source* オブジェクトの読み出し可能バッファをコピ
      ーすることで、ctypes のインスタンスを生成します。オプションの
      *offset* 引数では *source* バッファのオフセットをバイト単位で指
      定します。デフォルトではゼロです。もし *source* バッファが十分に
      大きくなければ、 "ValueError" が送出されます。

      引数 "pointer", "size", "offset" を指定して 監査イベント
      "ctypes.cdata/buffer" を送出します。

   from_address(address)

      このメソッドは *address* で指定されたメモリを使って ctypes 型の
      インスタンスを返します。 *address* は整数でなければなりません。

      このメソッドと、それを間接的に呼び出すメソッドは、引数 "address"
      を持つ 監査イベント "ctypes.cdata" を発生させます。

   from_param(obj)

      *obj* を ctypes の型に適合させるメソッドです。 外部関数の
      "argtypes" タプルにその型が含まれている場合、実際の関数呼び出し
      で使われるオブジェクトを渡して呼び出されます。 関数呼び出しの引
      数として使えるオブジェクトを返す必要があります。

      すべての ctypes のデータ型は、それが型のインスタンスであれば、
      *obj* を返すこのクラスメソッドのデフォルトの実装を持ちます。いく
      つかの型は、別のオブジェクトも受け付けます。

   in_dll(library, name)

      このメソッドは、共有ライブラリによってエクスポートされた ctypes
      型のインスタンスを返します。 *name* はエクスポートされたデータの
      名前で、 *library* はロードされた共有ライブラリです。

   ctypes データ型に共通のクラス変数:

   __pointer_type__

      対応する ctypes データ型に対して "POINTER()" を呼び出して作成し
      たポインタ型です。 まだポインタ型を作成していない場合、この属性
      は存在しません。

      Added in version 3.14.

   ctypes データ型共通のインスタンス変数:

   _b_base_

      ctypes 型データのインスタンスは、それ自身のメモリブロックを持た
      ず、基底オブジェクトのメモリブロックの一部を共有することがありま
      す。 "_b_base_" 読み出し専用属性は、メモリブロックを保持する
      ctypes の基底オブジェクトです。

   _b_needsfree_

      この読み出し専用の変数は、 ctypes データインスタンスが、それ自身
      に割り当てられたメモリブロックを持つとき true になります。それ以
      外の場合は false になります。

   _objects

      このメンバは "None" 、または、メモリブロックの内容が正しく保つた
      めに、生存させておかなくてはならない Python オブジェクトを持つデ
      ィクショナリです。このオブジェクトはデバッグでのみ使われます。決
      してディクショナリの内容を変更しないで下さい。


基本データ型
------------

class ctypes._SimpleCData

   この非公開クラスは、全ての基本的な ctypes データ型の基底クラスです
   。 これは基本的な ctypes データ型に共通の属性を持っているので、ここ
   で触れておきます。 "_SimpleCData" は "_CData" の子クラスなので、そ
   のメソッドと属性を継承しています。 ポインタそのものではなく、ポイン
   タも含まない ctypes データ型は、現在は pickle 化できます。

   インスタンスは一つだけ属性を持ちます:

   value

      この属性はインスタンスの実際の値を保持します。 整数型とポインタ
      型では整数、文字型では一文字の bytes オブジェクトまたは文字列、
      文字へのポインタ型では Python の bytes オブジェクトまたは文字列
      です。

      ctypes インスタンスから "value" 属性を取得すると、通常は毎回新し
      いオブジェクトが返されます。 "ctypes" は元のオブジェクトを返す機
      能を実装 *しておらず*、常に新しいオブジェクトを構築します。 これ
      は、ほかのすべての ctypes オブジェクトのインスタンスにも当てはま
      ります。

   各サブクラスには、以下のクラス属性があります:

   _type_

      Class attribute that contains an internal type code, as a
      single-character string. See 基本データ型 for a summary.

      Types marked * in the summary may be (or always are) aliases of
      a different "_SimpleCData" subclass, and will not necessarily
      use the listed type code. For example, if the platform's long,
      long long and time_t C types are the same, then "c_long",
      "c_longlong" and "c_time_t" all refer to a single class,
      "c_long", whose "_type_" code is "'l'". The "'L'" code will be
      unused.

      参考:

        "array" モジュールや struct モジュール、numpy などのサードパー
        ティー製モジュールでも、似てはいるものの少し異なる型コードを使
        用しています。

Fundamental data types, when returned as foreign function call
results, or, for example, by retrieving structure field members or
array items, are transparently converted to native Python types.  In
other words, if a foreign function has a "restype" of "c_char_p", you
will always receive a Python bytes object, *not* a "c_char_p"
instance.

基本データ型のサブクラスは、この動作を継承 *しません*。 したがって、外
部関数の "restype" が "c_void_p" のサブクラスの場合、関数呼び出しから
そのサブクラスのインスタンスを受け取ります。 もちろん、"value" 属性に
アクセスすればポインタの値を取得できます。

これらが基本 ctypes データ型です:

class ctypes.c_byte

   C の signed char データ型を表し、小整数として値を解釈します。コンス
   トラクタはオプションの整数初期化子を受け取ります。オーバーフローの
   チェックは行われません。

class ctypes.c_char

   C char データ型を表し、単一の文字として値を解釈します。コンストラク
   タはオプションの文字列初期化子を受け取り、その文字列の長さちょうど
   一文字である必要があります。

class ctypes.c_char_p

   C char* データ型を表し、ゼロ終端文字列へのポインタでなければなりま
   せん。バイナリデータを指す可能性のある一般的なポインタに対しては
   "POINTER(c_char)" を使わなければなりません。コンストラクタは整数の
   アドレスもしくはバイト列オブジェクトを受け取ります。

class ctypes.c_double

   C double データ型を表します。コンストラクタはオプションの浮動小数点
   数初期化子を受け取ります。

class ctypes.c_longdouble

   C long double データ型を表します。コンストラクタはオプションで浮動
   小数点数初期化子を受け取ります。 "sizeof(long double) ==
   sizeof(double)" であるプラットフォームでは "c_double" の別名です。

class ctypes.c_float

   C float データ型を表します。コンストラクタはオプションの浮動小数点
   数初期化子を受け取ります。

class ctypes.c_double_complex

   利用可能な場合に、C の double complex データ型を表します。 コンスト
   ラクタは省略可能な "complex" の初期値を受け付けます。

   Added in version 3.14.

class ctypes.c_float_complex

   利用可能な場合に、C の float complex データ型を表します。 コンスト
   ラクタは省略可能な "complex" の初期値を受け付けます。

   Added in version 3.14.

class ctypes.c_longdouble_complex

   利用可能な場合に、C の long double complex データ型を表します。 コ
   ンストラクタは省略可能な "complex" の初期値を受け付けます。

   Added in version 3.14.

class ctypes.c_int

   C signed int データ型を表します。コンストラクタはオプションの整数初
   期化子を受け取ります。オーバーフローのチェックは行われません。
   "sizeof(int) == sizeof(long)" であるプラットフォームでは、 "c_long"
   の別名です。

class ctypes.c_int8

   C の 8 ビットの signed int データ型を表します。 "c_byte" の別名です
   。

class ctypes.c_int16

   C 16-bit signed int データ型を表します。たいていは、 "c_short" の別
   名です。

class ctypes.c_int32

   C 32-bit signed int データ型を表します。たいていは、 "c_int" の別名
   です。

class ctypes.c_int64

   C 64-bit signed int データ型を表します。たいていは、 "c_longlong"
   の別名です。

class ctypes.c_long

   C signed long データ型を表します。コンストラクタはオプションの整数
   初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_longlong

   C の signed long long データ型を表します。 コンストラクタは省略可能
   な整数の初期値を受け付けますが、オーバーフローの検査は行いません。
   "sizeof(long long) == sizeof(long)" となるプラットフォームでは、
   "c_long" の別名です。

class ctypes.c_short

   C signed short データ型を表します。コンストラクタはオプションの整数
   初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_size_t

   C の "size_t" データ型を表します。 通常は、ほかの符号なし整数型の別
   名です。

class ctypes.c_ssize_t

   "Py_ssize_t" データ型を表します。 これは "size_t" の符号付き版、す
   なわち POSIX の "ssize_t" 型です。 通常は、ほかの整数型の別名です。

   Added in version 3.2.

class ctypes.c_time_t

   C の "time_t" データ型を表します。 通常は、ほかの整数型の別名です。

   Added in version 3.12.

class ctypes.c_ubyte

   C の unsigned char データ型を表し、小さな整数として値を解釈します。
   コンストラクタはオプションの整数初期化子を受け取ります; オーバーフ
   ローのチェックは行われません。

class ctypes.c_uint

   C の  unsigned int データ型を表します。コンストラクタはオプションの
   整数初期化子を受け取ります; オーバーフローのチェックは行われません
   。これは、 "sizeof(int) == sizeof(long)" であるプラットフォームでは
   "c_ulong" の別名です。

class ctypes.c_uint8

   C の 8 ビットの unsigned int データ型を表します。 "c_ubyte" の別名
   です。

class ctypes.c_uint16

   C 16-bit unsigned int データ型を表します。たいていは、 "c_ushort"
   の別名です。

class ctypes.c_uint32

   C 32-bit unsigned int データ型を表します。たいていは、 "c_uint" の
   別名です。

class ctypes.c_uint64

   C 64-bit unsigned int データ型を表します。たいていは、
   "c_ulonglong" の別名です。

class ctypes.c_ulong

   C unsigned long データ型を表します。コンストラクタはオプションの整
   数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_ulonglong

   Represents the C unsigned long long datatype.  The constructor
   accepts an optional integer initializer; no overflow checking is
   done. On platforms where "sizeof(long long) == sizeof(long)" it is
   an alias to "c_long".

class ctypes.c_ushort

   C unsigned short データ型を表します。コンストラクタはオプションの整
   数初期化子を受け取ります。オーバーフローのチェックは行われません。

class ctypes.c_void_p

   C void* データ型を表します。値は整数として表されます。コンストラク
   タはオプションの整数初期化子を受け取ります。

class ctypes.c_wchar

   C "wchar_t" データ型を表し、値は Unicode 文字列の単一の文字として解
   釈されます。コンストラクタはオプションの文字列初期化子を受け取り、
   その文字列の長さはちょうど一文字である必要があります。

class ctypes.c_wchar_p

   C wchar_t* データ型を表し、ゼロ終端ワイド文字列へのポインタでなけれ
   ばなりません。コンストラクタは整数のアドレスもしくは文字列を受け取
   ります。

class ctypes.c_bool

   C の bool データ型 (より正確には、 C99 以降の  _Bool) を表します。
   "True" または "False" の値を持ち、コンストラクタは真偽値と解釈でき
   るオブジェクトを受け取ります。

class ctypes.HRESULT

   関数やメソッドの呼び出しの成功またはエラーに関する情報を含む
   "HRESULT" 値を表します。

   利用可能な環境: Windows

class ctypes.py_object

   C PyObject* データ型を表します。引数なしでこれを呼び出すと "NULL"
   PyObject* ポインタを作成します。

   バージョン 3.14 で変更: "py_object" が *generic type* になりました
   。


Windows のデータ型
------------------

**ソースコード:** Lib/ctypes/wintypes.py

"ctypes.wintypes" モジュールは、Windows API で使う型を提供します。 多
くは "ctypes" で定義された型の別名です。 対応する C の定義は、
Microsoft の Windows のデータ型 のドキュメントを参照してください。
Windows 以外のプラットフォームでは、これらの型のサイズやレイアウトが
Windows のものと異なる場合があります。

バージョン 3.14 で変更: "HCONV"、"HCONVLIST"、"HCURSOR"、"HDDEDATA"、
"HDROP"、"HFILE"、"HRESULT"、"HSZ" が追加されました。

例えば:

   >>> from ctypes import POINTER
   >>> from ctypes.wintypes import LPRECT, RECT, SHORT
   >>> SHORT(-1).value
   -1
   >>> rect = RECT(0, 0, 100, 50)
   >>> rect.right, rect.bottom
   (100, 50)
   >>> LPRECT is POINTER(RECT)
   True


単純型
~~~~~~

以下の名前は、"ctypes" の基本型の別名です:

+----------------------------------------------------+----------------------------------------------------+
| Windows の型                                       | "ctypes" の型                                      |
|====================================================|====================================================|
| class ctypes.wintypes.BYTE class                   | "c_ubyte"                                          |
| ctypes.wintypes.BOOLEAN                            |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.CHAR                         | "c_char"                                           |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.WCHAR                        | "c_wchar"                                          |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.WORD class                   | "c_ushort"                                         |
| ctypes.wintypes.USHORT class ctypes.wintypes.ATOM  |                                                    |
| class ctypes.wintypes.LANGID                       |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.DWORD class                  | "c_ulong"                                          |
| ctypes.wintypes.ULONG class                        |                                                    |
| ctypes.wintypes.COLORREF class                     |                                                    |
| ctypes.wintypes.LCID class ctypes.wintypes.LCTYPE  |                                                    |
| class ctypes.wintypes.LGRPID                       |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.BOOL class                   | "c_long"                                           |
| ctypes.wintypes.LONG class ctypes.wintypes.HRESULT |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.INT class                    | "c_int"                                            |
| ctypes.wintypes.HFILE                              |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.UINT                         | "c_uint"                                           |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.SHORT                        | "c_short"                                          |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.DOUBLE                       | "c_double"                                         |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.FLOAT                        | "c_float"                                          |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LARGE_INTEGER                | "c_longlong"                                       |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.ULARGE_INTEGER               | "c_ulonglong"                                      |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPCSTR class                 | "c_char_p"                                         |
| ctypes.wintypes.LPSTR                              |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPCOLESTR class              | "c_wchar_p"                                        |
| ctypes.wintypes.LPOLESTR class                     |                                                    |
| ctypes.wintypes.OLESTR class                       |                                                    |
| ctypes.wintypes.LPCWSTR class                      |                                                    |
| ctypes.wintypes.LPWSTR                             |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPCVOID class                | "c_void_p"                                         |
| ctypes.wintypes.LPVOID                             |                                                    |
+----------------------------------------------------+----------------------------------------------------+

"LARGE_INTEGER" と "ULARGE_INTEGER" は整数の "value" 属性を公開し、
"LowPart"、"HighPart"、"QuadPart" フィールドは持ちません。

class ctypes.wintypes.WPARAM

   "c_void_p" と同じサイズの符号なし整数型です。

class ctypes.wintypes.LPARAM

   "c_void_p" と同じサイズの符号付き整数型です。

class ctypes.wintypes.VARIANT_BOOL

   "value" 属性が Python の "bool" である、16 ビットのブール型です。
   "value" に代入すると、真の値には "-1"、偽の値には "0" を格納します
   。


ハンドル型
~~~~~~~~~~

class ctypes.wintypes.HANDLE

   Windows ハンドルを表すために使う "c_void_p" の別名です。

class ctypes.wintypes.HACCEL
class ctypes.wintypes.HBITMAP
class ctypes.wintypes.HBRUSH
class ctypes.wintypes.HCOLORSPACE
class ctypes.wintypes.HCONV
class ctypes.wintypes.HCONVLIST
class ctypes.wintypes.HCURSOR
class ctypes.wintypes.HDC
class ctypes.wintypes.HDDEDATA
class ctypes.wintypes.HDESK
class ctypes.wintypes.HDROP
class ctypes.wintypes.HDWP
class ctypes.wintypes.HENHMETAFILE
class ctypes.wintypes.HFONT
class ctypes.wintypes.HGDIOBJ
class ctypes.wintypes.HGLOBAL
class ctypes.wintypes.HHOOK
class ctypes.wintypes.HICON
class ctypes.wintypes.HINSTANCE
class ctypes.wintypes.HKEY
class ctypes.wintypes.HKL
class ctypes.wintypes.HLOCAL
class ctypes.wintypes.HMENU
class ctypes.wintypes.HMETAFILE
class ctypes.wintypes.HMODULE
class ctypes.wintypes.HMONITOR
class ctypes.wintypes.HPALETTE
class ctypes.wintypes.HPEN
class ctypes.wintypes.HRGN
class ctypes.wintypes.HRSRC
class ctypes.wintypes.HSTR
class ctypes.wintypes.HSZ
class ctypes.wintypes.HTASK
class ctypes.wintypes.HWINSTA
class ctypes.wintypes.HWND
class ctypes.wintypes.SC_HANDLE
class ctypes.wintypes.SERVICE_STATUS_HANDLE

   特定の Windows API で使う "HANDLE" の別名です。 "HFILE" は "INT" の
   別名であり、上の単純型の一覧に含まれます。


構造体
~~~~~~

以下の型は "ctypes.Structure" のサブクラスです。

class ctypes.wintypes.RECT
class ctypes.wintypes.RECTL
class ctypes.wintypes.tagRECT

   "left"、"top"、"right"、"bottom" フィールドを持つ長方形です。 すべ
   てのフィールドは "LONG" 型です。

class ctypes.wintypes.SMALL_RECT

   "Left"、"Top"、"Right"、"Bottom" フィールドを持つ長方形です。 すべ
   てのフィールドは "SHORT" 型です。

class ctypes.wintypes.POINT
class ctypes.wintypes.POINTL
class ctypes.wintypes.tagPOINT

   "x" と "y" フィールドを持つ点です。 どちらのフィールドも "LONG" 型
   です。

class ctypes.wintypes.SIZE
class ctypes.wintypes.SIZEL
class ctypes.wintypes.tagSIZE

   "cx" と "cy" フィールドを持つ寸法です。 どちらのフィールドも "LONG"
   型です。

class ctypes.wintypes.FILETIME

   "dwLowDateTime" と "dwHighDateTime" フィールドを持つファイル時刻で
   す。 どちらのフィールドも "DWORD" 型です。

class ctypes.wintypes.MSG
class ctypes.wintypes.tagMSG

   以下のフィールドを持つ Windows メッセージです:

   +----------------------------------------------------+----------------------------------------------------+
   | フィールド                                         | 型                                                 |
   |====================================================|====================================================|
   | "hWnd"                                             | "HWND"                                             |
   +----------------------------------------------------+----------------------------------------------------+
   | "message"                                          | "UINT"                                             |
   +----------------------------------------------------+----------------------------------------------------+
   | "wParam"                                           | "WPARAM"                                           |
   +----------------------------------------------------+----------------------------------------------------+
   | "lParam"                                           | "LPARAM"                                           |
   +----------------------------------------------------+----------------------------------------------------+
   | "time"                                             | "DWORD"                                            |
   +----------------------------------------------------+----------------------------------------------------+
   | "pt"                                               | "POINT"                                            |
   +----------------------------------------------------+----------------------------------------------------+

class ctypes.wintypes.WIN32_FIND_DATAA
class ctypes.wintypes.WIN32_FIND_DATAW

   Windows のファイル検索関数が使う構造体で、以下のフィールドを持ちま
   す。 ファイル名に "WIN32_FIND_DATAA" は "CHAR"、"WIN32_FIND_DATAW"
   は "WCHAR" を使います。

   +----------------------------------------------------+----------------------------------------------------+
   | フィールド                                         | 型                                                 |
   |====================================================|====================================================|
   | "dwFileAttributes"                                 | "DWORD"                                            |
   +----------------------------------------------------+----------------------------------------------------+
   | "ftCreationTime", "ftLastAccessTime",              | "FILETIME"                                         |
   | "ftLastWriteTime"                                  |                                                    |
   +----------------------------------------------------+----------------------------------------------------+
   | "nFileSizeHigh", "nFileSizeLow"                    | "DWORD"                                            |
   +----------------------------------------------------+----------------------------------------------------+
   | "dwReserved0", "dwReserved1"                       | "DWORD"                                            |
   +----------------------------------------------------+----------------------------------------------------+
   | "cFileName"                                        | "MAX_PATH" 文字の配列                              |
   +----------------------------------------------------+----------------------------------------------------+
   | "cAlternateFileName"                               | 14 文字の配列                                      |
   +----------------------------------------------------+----------------------------------------------------+


ポインタ型
~~~~~~~~~~

以下の名前は、2 列目の型を *T* とする "ctypes.POINTER(T)" の別名です:

+----------------------------------------------------+----------------------------------------------------+
| ポインタ型                                         | 参照先の型                                         |
|====================================================|====================================================|
| class ctypes.wintypes.LPBOOL class                 | "BOOL"                                             |
| ctypes.wintypes.PBOOL                              |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PBOOLEAN                     | "BOOLEAN"                                          |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPBYTE class                 | "BYTE"                                             |
| ctypes.wintypes.PBYTE                              |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PCHAR                        | "CHAR"                                             |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPCOLORREF                   | "COLORREF"                                         |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPDWORD class                | "DWORD"                                            |
| ctypes.wintypes.PDWORD                             |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPFILETIME class             | "FILETIME"                                         |
| ctypes.wintypes.PFILETIME                          |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PFLOAT                       | "FLOAT"                                            |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPHANDLE class               | "HANDLE"                                           |
| ctypes.wintypes.PHANDLE                            |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PHKEY                        | "HKEY"                                             |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPHKL                        | "HKL"                                              |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPINT class                  | "INT"                                              |
| ctypes.wintypes.PINT                               |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PLARGE_INTEGER               | "LARGE_INTEGER"                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PLCID                        | "LCID"                                             |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPLONG class                 | "LONG"                                             |
| ctypes.wintypes.PLONG                              |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPMSG class                  | "MSG"                                              |
| ctypes.wintypes.PMSG                               |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPPOINT class                | "POINT"                                            |
| ctypes.wintypes.PPOINT                             |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PPOINTL                      | "POINTL"                                           |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPRECT class                 | "RECT"                                             |
| ctypes.wintypes.PRECT                              |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPRECTL class                | "RECTL"                                            |
| ctypes.wintypes.PRECTL                             |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPSC_HANDLE                  | "SC_HANDLE"                                        |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PSHORT                       | "SHORT"                                            |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPSIZE class                 | "SIZE"                                             |
| ctypes.wintypes.PSIZE                              |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPSIZEL class                | "SIZEL"                                            |
| ctypes.wintypes.PSIZEL                             |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PSMALL_RECT                  | "SMALL_RECT"                                       |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPUINT class                 | "UINT"                                             |
| ctypes.wintypes.PUINT                              |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PULARGE_INTEGER              | "ULARGE_INTEGER"                                   |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PULONG                       | "ULONG"                                            |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PUSHORT                      | "USHORT"                                           |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.PWCHAR                       | "WCHAR"                                            |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPWIN32_FIND_DATAA class     | "WIN32_FIND_DATAA"                                 |
| ctypes.wintypes.PWIN32_FIND_DATAA                  |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPWIN32_FIND_DATAW class     | "WIN32_FIND_DATAW"                                 |
| ctypes.wintypes.PWIN32_FIND_DATAW                  |                                                    |
+----------------------------------------------------+----------------------------------------------------+
| class ctypes.wintypes.LPWORD class                 | "WORD"                                             |
| ctypes.wintypes.PWORD                              |                                                    |
+----------------------------------------------------+----------------------------------------------------+


定数と関数
~~~~~~~~~~

ctypes.wintypes.MAX_PATH

   "WIN32_FIND_DATAA" と "WIN32_FIND_DATAW" のファイル名配列のサイズと
   して使う値 "260" です。

ctypes.wintypes.RGB(red, green, blue)

   "COLORREF" の値を Python の整数として返します。 *red*、*green*、
   *blue* 引数は "0" から "255" までの整数で、各色成分の強度を指定しま
   す。

      >>> from ctypes.wintypes import RGB
      >>> hex(RGB(255, 128, 0))
      '0x80ff'


構造化データ型
--------------

class ctypes.Union(*args, **kw)

   ネイティブのバイトオーダーでの共用体のための抽象ベースクラス。

   共用体は構造体と共通の属性と動作を持ちます。 詳細は "Structure" の
   ドキュメントを参照してください。

class ctypes.BigEndianUnion(*args, **kw)

   *ビックエンディアン* バイトオーダーでの共用体のための抽象ベースクラ
   ス。

   Added in version 3.11.

class ctypes.LittleEndianUnion(*args, **kw)

   *リトルエンディアン* バイトオーダーでの共用体のための抽象ベースクラ
   ス。

   Added in version 3.11.

class ctypes.BigEndianStructure(*args, **kw)

   *ビックエンディアン* バイトオーダーでの構造体のための抽象ベースクラ
   ス。

class ctypes.LittleEndianStructure(*args, **kw)

   *リトルエンディアン* バイトオーダーでの構造体のための抽象ベースクラ
   ス。

ネイティブではないバイトオーダーを持つ構造体および共用体にポインタ型フ
ィールドあるいはポインタ型フィールドを含む他のどんなデータ型をも入れる
ことはできません。

class ctypes.Structure(*args, **kw)

   *ネイティブ* のバイトオーダーでの構造体のための抽象ベースクラス。

   Concrete structure and union types must be created by subclassing
   one of these types, and at least define a "_fields_" class
   variable. "ctypes" will create *descriptor*s which allow reading
   and writing the fields by direct attribute accesses.  These are the

   _fields_

      構造体のフィールドを定義するシーケンス。要素は2要素タプルか3要素
      タプルでなければなりません。第一要素はフィールドの名前です。第二
      要素はフィールドの型を指定します。それはどんな ctypes データ型で
      も構いません。

      "c_int" のような整数型のために、オプションの第三要素を与えること
      ができます。フィールドのビット幅を定義する正の小整数である必要が
      あります。

      一つの構造体と共用体の中で、フィールド名はただ一つである必要があ
      ります。これはチェックされません。名前が繰り返しでてきたときにア
      クセスできるのは一つのフィールドだけです。

      Structure サブクラスを定義するクラス文の *後で* 、 "_fields_" ク
      ラス変数を定義することができます。これにより、次のように自身を直
      接または間接的に参照するデータ型を作成できるようになります:

         class List(Structure):
             pass
         List._fields_ = [("pnext", POINTER(List)),
                          ...
                         ]

      "_fields_" クラス変数は 1 回だけ設定できます。 その後の代入では
      "AttributeError" を送出します。

      Additionally, the "_fields_" class variable must be defined
      before the structure or union type is first used: an instance or
      subclass is created, "sizeof()" is called on it, and so on.
      Later assignments to "_fields_" will raise an "AttributeError".
      If "_fields_" has not been set before such use, the structure or
      union will have no own fields, as if "_fields_" was empty.

      構造体型のサブクラスのサブクラスは、基底クラスのフィールドを継承
      し、さらに自身で "_fields_" を定義していれば、そのフィールドも持
      ちます。

   _pack_

      インスタンス内の構造体フィールドのアラインメントを上書きするため
      の、省略可能な小さな整数です。

      これは MSVC 互換のメモリレイアウトでのみ実装されています
      ("_layout_" を参照)。

      "_pack_" に 0 を設定することは、設定しないことと同じです。 それ
      以外の場合、値は 2 のべき乗の正の整数でなければなりません。 効果
      は C の "#pragma pack(N)" と同じですが、"ctypes" はコンパイラが
      受け付けるより大きな *n* を許可する場合があります。

      "_fields_" に代入する時点で "_pack_" が定義されていないと、効果
      はありません。

      バージョン 3.14 で非推奨、バージョン 3.19 で削除予定: 歴史的な理
      由から、"_pack_" がゼロ以外の場合、デフォルトで MSVC 互換のレイ
      アウトを使用します。 Windows 以外のプラットフォームでは、このデ
      フォルトの動作は非推奨であり、Python 3.19 ではエラーになる予定で
      す。 このレイアウトを意図している場合は、"_layout_" に "'ms'" を
      明示的に設定してください。

   _align_

      構造体をメモリへパックしたりメモリからアンパックしたりするときの
      アラインメントを大きくする、省略可能な小さな整数です。

      値は負であってはなりません。 効果は GCC の
      "__attribute__((aligned(N)))" や MSVC の "#pragma align(N)" と同
      じですが、"ctypes" はコンパイラが拒否する値を許可する場合があり
      ます。

      "_align_" は、構造体のアラインメント要件を *大きくする* ことしか
      できません。 0 や 1 に設定しても効果はありません。

      2 のべき乗でない値の使用は推奨されず、予想外の動作を引き起こす場
      合があります。

      "_fields_" に代入する時点で "_align_" が定義されていないと、効果
      はありません。

      Added in version 3.13.

   _layout_

      構造体や共用体のレイアウト名を指定する、省略可能な文字列です。
      現在は以下の値を指定できます:

      * ""ms"": Microsoft コンパイラ (MSVC) が使うレイアウトです。 GCC
        と Clang では、"__attribute__((ms_struct))" でこのレイアウトを
        選べます。

      * ""gcc-sysv"": Linux や macOS で使われる、System V または「SysV
        に似た」データモデルで GCC が使うレイアウトです。 このレイアウ
        トでは、"_pack_" を設定しないか、ゼロにする必要があります。

      明示的に設定しない場合、"ctypes" はプラットフォームの慣例に合う
      デフォルト値を使います。 このデフォルト値は、例えば新しいプラッ
      トフォームが正式にサポートされたり、似たプラットフォーム間の違い
      が見つかったりした場合など、将来の Python リリースで変わる可能性
      があります。 現在のデフォルト値は次のとおりです:

      * Windows の場合: ""ms""

      * "_pack_" を指定した場合: ""ms"" (この動作は非推奨です。
        "_pack_" のドキュメントを参照してください)。

      * それ以外の場合: ""gcc-sysv""

      "_fields_" に代入する時点で "_layout_" が定義されていないと、効
      果はありません。

      Added in version 3.14.

   _anonymous_

      無名 (匿名) フィールドの名前が並べあげられたオプションのシーケン
      ス。 "_fields_" が代入されたとき、 "_anonymous_" がすでに定義さ
      れていなければなりません。そうでなければ、何ら影響はありません。

      この変数に列挙するフィールドは、構造体型または共用体型のフィール
      ドでなければなりません。 "ctypes" は、構造体型にデスクリプタを作
      成し、構造体や共用体のフィールドを作成せずに、入れ子のフィールド
      へ直接アクセスできるようにします。

      型の例です (Windows):

         class _U(Union):
             _fields_ = [("lptdesc", POINTER(TYPEDESC)),
                         ("lpadesc", POINTER(ARRAYDESC)),
                         ("hreftype", HREFTYPE)]

         class TYPEDESC(Structure):
             _anonymous_ = ("u",)
             _fields_ = [("u", _U),
                         ("vt", VARTYPE)]

      "TYPEDESC" 構造体はCOMデータ型を表現しており、 "vt" フィールドは
      共用体フィールドのどれが有効であるかを指定します。 "u" フィール
      ドは匿名フィールドとして定義されているため、 "TYPEDESC" インスタ
      ンスからそのメンバーに直接アクセスできます。 "td.lptdesc" と
      "td.u.lptdesc" は同等ですが、前者がより高速です。 なぜなら一時的
      な共用体インスタンスを作る必要がないためです。

         td = TYPEDESC()
         td.vt = VT_PTR
         td.lptdesc = POINTER(some_type)
         td.u.lptdesc = POINTER(some_type)

   構造体のサブクラスのサブクラスを定義することができ、基底クラスのフ
   ィールドを継承します。 サブクラス定義に別の "_fields_" 変数がある場
   合は、この中で指定されたフィールドは基底クラスのフィールドへ追加さ
   れます。

   構造体と共用体のコンストラクタは位置引数とキーワード引数の両方を受
   け取ります。位置引数は "_fields_" の中に現れたのと同じ順番でメンバ
   ーフィールドを初期化するために使われます。コンストラクタのキーワー
   ド引数は属性代入として解釈され、そのため、同じ名前をもつ "_fields_"
   を初期化するか、 "_fields_" に存在しない名前に対しては新しい属性を
   作ります。

class ctypes.CField(*args, **kw)

   "Structure" と "Union" のフィールドのデスクリプタです。 例えば次の
   ように使います。

      >>> class Color(Structure):
      ...     _fields_ = (
      ...         ('red', c_uint8),
      ...         ('green', c_uint8),
      ...         ('blue', c_uint8),
      ...         ('intense', c_bool, 1),
      ...         ('blinking', c_bool, 1),
      ...    )
      ...
      >>> Color.red
      <ctypes.CField 'red' type=c_ubyte, ofs=0, size=1>
      >>> Color.green.type
      <class 'ctypes.c_ubyte'>
      >>> Color.blue.byte_offset
      2
      >>> Color.intense
      <ctypes.CField 'intense' type=c_bool, ofs=3, bit_size=1, bit_offset=0>
      >>> Color.blinking.bit_offset
      1

   すべての属性は読み出し専用です。

   "CField" オブジェクトは "_fields_" を通じて作成されます。 このクラ
   スを直接インスタンス化しないでください。

   Added in version 3.14: 以前のデスクリプタは "offset" と "size" 属性
   、および読みやすい文字列表現だけを持ち、"CField" クラスは直接利用で
   きませんでした。

   name

      文字列で表したフィールド名です。

   type

      ctypes のクラス で表したフィールドの型です。

   offset
   byte_offset

      フィールドのオフセット (バイト単位) です。

      ビットフィールドでは、これはバイト境界に整列した、元になる *格納
      単位* のオフセットです。 "bit_offset" を参照してください。

   byte_size

      フィールドのサイズ (バイト単位) です。

      ビットフィールドでは、これは元になる *格納単位* のサイズです。
      通常はビットフィールドの型と同じサイズです。

   size

      ビットフィールドでない場合は、"byte_size" と同じです。

      ビットフィールドでは、"bit_size" と "bit_offset" をビット単位で
      まとめた、後方互換性のための値を格納します。 代わりに、これらの
      明示的な属性を使ってください。

   is_bitfield

      ビットフィールドであれば真です。

   bit_offset
   bit_size

      ビットフィールドの *格納単位* 内での位置です。 つまり、
      "byte_offset" から始まる "byte_size" バイトのメモリ内での位置で
      す。

      To get the field's value, read the storage unit as an integer,
      shift left by "bit_offset" and take the "bit_size" least
      significant bits.

      ビットフィールドでない場合、"bit_offset" はゼロで、"bit_size" は
      "byte_size * 8" に等しくなります。

   is_anonymous

      このフィールドが匿名であれば真です。 つまり、外側の構造体や共用
      体に統合される入れ子のサブフィールドを含む場合です。


配列とポインタ
--------------

class ctypes.Array(*args)

   配列のための抽象基底クラスです。

   具体的な配列型を作成する推奨の方法は、任意の "ctypes" データ型に非
   負の整数を掛けることです。 この型をサブクラス化し、"_length_" と
   "_type_" クラス変数を定義する方法もあります。 配列の要素は、通常の
   添字やスライスによるアクセスで読み書きできます。 スライスを読み出し
   た場合、結果のオブジェクト自体は "Array" では *ありません*。

   配列は、要素の型について ジェネリック です。

   _length_

      配列の要素数を指定する正の整数。範囲外の添え字を指定すると、
      "IndexError" が送出されます。"len()" がこの整数を返します。

   _type_

      配列内の各要素の型を指定します。

   配列のサブクラスのコンストラクタは、位置引数を受け付けて、配列を順
   番に初期化するために使用します。

ctypes.ARRAY(type, length)

   配列を作成します。 *type* を "ctypes" のデータ型、*length* を整数と
   した "type * length" と同じです。

   バージョン 3.14 で ソフト非推奨 <Soft deprecated>: 代わりに乗算を使
   用してください。

class ctypes._Pointer

   ポインタのためのプライベートな抽象基底クラスです。

   具象ポインタ型は、ポイント先の型を持つ "POINTER()" を呼び出すことで
   、作成できます。これは、 "pointer()" により自動的に行われます。

   ポインタが配列を指す場合、その配列の要素は、標準の添え字とスライス
   によるアクセスを使用して読み書きが行えます。ポインタオブジェクトに
   は、サイズがないため、 "len()" 関数は "TypeError" を送出します。負
   の添え字は、(C と同様に) ポインタの *前* のメモリから読み込み、範囲
   外の添え字はおそらく (幸運な場合でも) アクセス違反によりクラッシュ
   を起こします。

   _type_

      ポイント先の型を指定します。

   contents

      ポインタが指すオブジェクトを返します。この属性に割り当てると、ポ
      インタが割り当てられたオブジェクトを指すようになります。


例外
----

exception ctypes.ArgumentError

   この例外は外部関数呼び出しが渡された引数を変換できなかったときに送
   出されます。

exception ctypes.COMError(hresult, text, details)

   COM メソッドの呼び出しが失敗した場合に送出される例外です。

   hresult

      エラーコードを表す整数値です。

   text

      エラーメッセージです。

   details

      5 要素のタプル "(descr, source, helpfile, helpcontext, progid)"
      です。

      *descr* は説明文です。 *source* は、エラーを発生させたクラスやア
      プリケーションの、言語に依存する "ProgID" です。 *helpfile* はヘ
      ルプファイルのパスです。 *helpcontext* はヘルプコンテキスト識別
      子です。 *progid* は、エラーを定義したインターフェースの
      "ProgID" です。

   利用可能な環境: Windows

   Added in version 3.14.
