python-doc-tw.github.io/library/ctypes.html at master · python-doc-tw/python-doc-tw.github.io

History

2635 lines (2500 loc) · 259 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

741

742

743

744

745

746

747

748

749

750

751

752

753

754

755

756

757

758

759

760

761

762

763

764

765

766

767

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

800

801

802

803

804

805

806

807

808

809

810

811

812

813

814

815

816

817

818

819

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

863

864

865

866

867

868

869

870

871

872

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

918

919

920

921

922

923

924

925

926

927

928

929

930

931

932

933

934

935

936

937

938

939

940

941

942

943

944

945

946

947

948

949

950

951

952

953

954

955

956

957

958

959

960

961

962

963

964

965

966

967

968

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

985

986

987

988

989

990

991

992

993

994

995

996

997

998

999

1000

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>16.16. ctypes — A foreign function library for Python — Python 3.7.0 說明文件</title>

title="在 Python 3.7.0 說明文件中搜尋"

href="../_static/opensearch.xml"/>

</head><body>

<ul>

<a href="../genindex.html" title="General Index"

accesskey="I">索引</a></li>

<a href="../py-modindex.html" title="Python 模組索引"

>模組</a> |</li>

<a href="concurrency.html" title="17. Concurrent Execution"

accesskey="N">下一頁</a> |</li>

<a href="errno.html" title="16.15. errno — Standard errno system symbols"

accesskey="P">上一頁</a> |</li>

<li><img src="../_static/py.png" alt=""

style="vertical-align: middle; margin-top: -1px"/></li>

<li><a href="https://www.python.org/">Python</a> »</li>

<li>

zh_TW

3.7.0

<a href="../index.html">Documentation </a> »

</li>

<li class="nav-item nav-item-1"><a href="index.html" >Python 標準函式庫 (Standard Library)</a> »</li>

<li class="nav-item nav-item-2"><a href="allos.html" accesskey="U">16. Generic Operating System Services</a> »</li>

</form>

</div>

</li>

</ul>

</div>

<h1>16.16. <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> — A foreign function library for Python<a class="headerlink" href="#module-ctypes" title="本標題的永久連結">¶</a></h1>

data types, and allows calling functions in DLLs or shared libraries. It can be

used to wrap these libraries in pure Python.

<h2>16.16.1. ctypes tutorial<a class="headerlink" href="#ctypes-tutorial" title="本標題的永久連結">¶</a></h2>

Note: The code samples in this tutorial use <a class="reference internal" href="doctest.html#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate">doctest</code></a> to make sure that

they actually work. Since some code samples behave differently under Linux,

Windows, or Mac OS X, they contain doctest directives in comments.

Note: Some code samples reference the ctypes <a class="reference internal" href="#ctypes.c_int" title="ctypes.c_int"><code class="xref py py-class docutils literal notranslate">c_int</code></a> type. On platforms

where <code class="docutils literal notranslate">sizeof(long) == sizeof(int)</code> it is an alias to <a class="reference internal" href="#ctypes.c_long" title="ctypes.c_long"><code class="xref py py-class docutils literal notranslate">c_long</code></a>.

So, you should not be confused if <a class="reference internal" href="#ctypes.c_long" title="ctypes.c_long"><code class="xref py py-class docutils literal notranslate">c_long</code></a> is printed if you would expect

<a class="reference internal" href="#ctypes.c_int" title="ctypes.c_int"><code class="xref py py-class docutils literal notranslate">c_int</code></a> — they are actually the same type.

<h3>16.16.1.1. Loading dynamic link libraries<a class="headerlink" href="#loading-dynamic-link-libraries" title="本標題的永久連結">¶</a></h3>

objects, for loading dynamic link libraries.

You load libraries by accessing them as attributes of these objects. cdll

loads libraries which export functions using the standard <code class="docutils literal notranslate">cdecl</code> calling

convention, while windll libraries call functions using the <code class="docutils literal notranslate">stdcall</code>

calling convention. oledll also uses the <code class="docutils literal notranslate">stdcall</code> calling convention, and

assumes the functions return a Windows <code class="xref c c-type docutils literal notranslate">HRESULT</code> error code. The error

code is used to automatically raise an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-class docutils literal notranslate">OSError</code></a> exception when the

function call fails.

3.3 版更變: Windows errors used to raise <a class="reference internal" href="exceptions.html#WindowsError" title="WindowsError"><code class="xref py py-exc docutils literal notranslate">WindowsError</code></a>, which is now an alias

of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate">OSError</code></a>.

</div>

Here are some examples for Windows. Note that <code class="docutils literal notranslate">msvcrt</code> is the MS standard C

library containing most standard C functions, and uses the cdecl calling

convention:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> from ctypes import *

>>> print(windll.kernel32)

>>> print(cdll.msvcrt)

>>> libc = cdll.msvcrt

>>>

</pre></div>

</div>

Windows appends the usual <code class="docutils literal notranslate">.dll</code> file suffix automatically.

備註

Accessing the standard C library through <code class="docutils literal notranslate">cdll.msvcrt</code> will use an

outdated version of the library that may be incompatible with the one

being used by Python. Where possible, use native Python functionality,

or else import and use the <code class="docutils literal notranslate">msvcrt</code> module.

</div>

On Linux, it is required to specify the filename including the extension to

load a library, so attribute access can not be used to load libraries. Either the

<code class="xref py py-meth docutils literal notranslate">LoadLibrary()</code> method of the dll loaders should be used, or you should load

the library by creating an instance of CDLL by calling the constructor:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> cdll.LoadLibrary("libc.so.6")

>>> libc = CDLL("libc.so.6")

>>> libc

>>>

</pre></div>

</div>

<h3>16.16.1.2. Accessing functions from loaded dlls<a class="headerlink" href="#accessing-functions-from-loaded-dlls" title="本標題的永久連結">¶</a></h3>

Functions are accessed as attributes of dll objects:

>>> libc.printf

<_FuncPtr object at 0x...>

>>> print(windll.kernel32.GetModuleHandleA)

<_FuncPtr object at 0x...>

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

>>>

</pre></div>

</div>

Note that win32 system dlls like <code class="docutils literal notranslate">kernel32</code> and <code class="docutils literal notranslate">user32</code> often export ANSI

as well as UNICODE versions of a function. The UNICODE version is exported with

an <code class="docutils literal notranslate">W</code> appended to the name, while the ANSI version is exported with an <code class="docutils literal notranslate">A</code>

appended to the name. The win32 <code class="docutils literal notranslate">GetModuleHandle</code> function, which returns a

module handle for a given module name, has the following C prototype, and a

macro is used to expose one of them as <code class="docutils literal notranslate">GetModuleHandle</code> depending on whether

UNICODE is defined or not:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>/* ANSI version */

HMODULE GetModuleHandleA(LPCSTR lpModuleName);

/* UNICODE version */

HMODULE GetModuleHandleW(LPCWSTR lpModuleName);

</pre></div>

</div>

windll does not try to select one of them by magic, you must access the

version you need by specifying <code class="docutils literal notranslate">GetModuleHandleA</code> or <code class="docutils literal notranslate">GetModuleHandleW</code>

explicitly, and then call it with bytes or string objects respectively.

Sometimes, dlls export functions with names which aren’t valid Python

identifiers, like <code class="docutils literal notranslate">"??2@YAPAXI@Z"</code>. In this case you have to use

<a class="reference internal" href="functions.html#getattr" title="getattr"><code class="xref py py-func docutils literal notranslate">getattr()</code></a> to retrieve the function:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> getattr(cdll.msvcrt, "??2@YAPAXI@Z")

<_FuncPtr object at 0x...>

>>>

</pre></div>

</div>

On Windows, some dlls export functions not by name but by ordinal. These

functions can be accessed by indexing the dll object with the ordinal number:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> 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__

AttributeError: function ordinal 0 not found

>>>

</pre></div>

</div>

<h3>16.16.1.3. Calling functions<a class="headerlink" href="#calling-functions" title="本標題的永久連結">¶</a></h3>

You can call these functions like any other Python callable. This example uses

the <code class="docutils literal notranslate">time()</code> function, which returns system time in seconds since the Unix

epoch, and the <code class="docutils literal notranslate">GetModuleHandleA()</code> function, which returns a win32 module

handle.

This example calls both functions with a NULL pointer (<code class="docutils literal notranslate">None</code> should be used

as the NULL pointer):

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> print(libc.time(None))

1150640792

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

0x1d000000

>>>

</pre></div>

</div>

備註

<a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> may raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> after calling the function, if

it detects that an invalid number of arguments were passed. This behavior

should not be relied upon. It is deprecated in 3.6.2, and will be removed

in 3.7.

</div>

<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate">ValueError</code></a> is raised when you call an <code class="docutils literal notranslate">stdcall</code> function with the

<code class="docutils literal notranslate">cdecl</code> calling convention, or vice versa:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> cdll.kernel32.GetModuleHandleA(None)

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

ValueError: Procedure probably called with not enough arguments (4 bytes missing)

>>>

>>> windll.msvcrt.printf(b"spam")

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

ValueError: Procedure probably called with too many arguments (4 bytes in excess)

>>>

</pre></div>

</div>

To find out the correct calling convention you have to look into the C header

file or the documentation for the function you want to call.

On Windows, <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> uses win32 structured exception handling to prevent

crashes from general protection faults when functions are called with invalid

argument values:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> windll.kernel32.GetModuleHandleA(32)

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

OSError: exception: access violation reading 0x00000020

>>>

</pre></div>

</div>

There are, however, enough ways to crash Python with <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a>, so you

should be careful anyway. The <a class="reference internal" href="faulthandler.html#module-faulthandler" title="faulthandler: Dump the Python traceback."><code class="xref py py-mod docutils literal notranslate">faulthandler</code></a> module can be helpful in

debugging crashes (e.g. from segmentation faults produced by erroneous C library

calls).

<code class="docutils literal notranslate">None</code>, integers, bytes objects and (unicode) strings are the only native

Python objects that can directly be used as parameters in these function calls.

<code class="docutils literal notranslate">None</code> is passed as a C <code class="docutils literal notranslate">NULL</code> pointer, bytes objects and strings are passed

as pointer to the memory block that contains their data (<code class="xref c c-type docutils literal notranslate">char *</code> or

<code class="xref c c-type docutils literal notranslate">wchar_t *</code>). Python integers are passed as the platforms default C

<code class="xref c c-type docutils literal notranslate">int</code> type, their value is masked to fit into the C type.

Before we move on calling functions with other parameter types, we have to learn

more about <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> data types.

</div>

<h3>16.16.1.4. Fundamental data types<a class="headerlink" href="#fundamental-data-types" title="本標題的永久連結">¶</a></h3>

</colgroup>

<tr class="row-odd"><th class="head">ctypes type</th>

<th class="head">Python type</th>

</tr>

</thead>

</tr>

<td>1-character bytes object</td>

</tr>

<tr class="row-even"><td><a class="reference internal" href="#ctypes.c_wchar" title="ctypes.c_wchar"><code class="xref py py-class docutils literal notranslate">c_wchar</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">wchar_t</code></td>

<td>1-character string</td>

</tr>

</tr>

<tr class="row-even"><td><a class="reference internal" href="#ctypes.c_ubyte" title="ctypes.c_ubyte"><code class="xref py py-class docutils literal notranslate">c_ubyte</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">unsigned char</code></td>

</tr>

<tr class="row-odd"><td><a class="reference internal" href="#ctypes.c_short" title="ctypes.c_short"><code class="xref py py-class docutils literal notranslate">c_short</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">short</code></td>

</tr>

<tr class="row-even"><td><a class="reference internal" href="#ctypes.c_ushort" title="ctypes.c_ushort"><code class="xref py py-class docutils literal notranslate">c_ushort</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">unsigned short</code></td>

</tr>

</tr>

<td><code class="xref c c-type docutils literal notranslate">unsigned int</code></td>

</tr>

</tr>

<tr class="row-even"><td><a class="reference internal" href="#ctypes.c_ulong" title="ctypes.c_ulong"><code class="xref py py-class docutils literal notranslate">c_ulong</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">unsigned long</code></td>

</tr>

<tr class="row-odd"><td><a class="reference internal" href="#ctypes.c_longlong" title="ctypes.c_longlong"><code class="xref py py-class docutils literal notranslate">c_longlong</code></a></td>

</tr>

<tr class="row-even"><td><a class="reference internal" href="#ctypes.c_ulonglong" title="ctypes.c_ulonglong"><code class="xref py py-class docutils literal notranslate">c_ulonglong</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">unsigned __int64</code> or

<code class="xref c c-type docutils literal notranslate">unsigned long long</code></td>

</tr>

</tr>

<tr class="row-even"><td><a class="reference internal" href="#ctypes.c_ssize_t" title="ctypes.c_ssize_t"><code class="xref py py-class docutils literal notranslate">c_ssize_t</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">ssize_t</code> or

<code class="xref c c-type docutils literal notranslate">Py_ssize_t</code></td>

</tr>

<tr class="row-odd"><td><a class="reference internal" href="#ctypes.c_float" title="ctypes.c_float"><code class="xref py py-class docutils literal notranslate">c_float</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">float</code></td>

<td>float</td>

</tr>

<tr class="row-even"><td><a class="reference internal" href="#ctypes.c_double" title="ctypes.c_double"><code class="xref py py-class docutils literal notranslate">c_double</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">double</code></td>

<td>float</td>

</tr>

<tr class="row-odd"><td><a class="reference internal" href="#ctypes.c_longdouble" title="ctypes.c_longdouble"><code class="xref py py-class docutils literal notranslate">c_longdouble</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">long double</code></td>

<td>float</td>

</tr>

<td><code class="xref c c-type docutils literal notranslate">char *</code> (NUL terminated)</td>

<td>bytes object or <code class="docutils literal notranslate">None</code></td>

</tr>

<tr class="row-odd"><td><a class="reference internal" href="#ctypes.c_wchar_p" title="ctypes.c_wchar_p"><code class="xref py py-class docutils literal notranslate">c_wchar_p</code></a></td>

<td><code class="xref c c-type docutils literal notranslate">wchar_t *</code> (NUL terminated)</td>

<td>string or <code class="docutils literal notranslate">None</code></td>

</tr>

</tr>

</tbody>

</table>

<li>The constructor accepts any object with a truth value.</li>

</ol>

All these types can be created by calling them with an optional initializer of

the correct type and value:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> c_int()

c_long(0)

>>> c_wchar_p("Hello, World")

c_wchar_p(140018365411392)

>>> c_ushort(-3)

c_ushort(65533)

>>>

</pre></div>

</div>

Since these types are mutable, their value can also be changed afterwards:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> i = c_int(42)

>>> print(i)

c_long(42)

>>> print(i.value)

42

>>> i.value = -99

>>> print(i.value)

-99

>>>

</pre></div>

</div>

Assigning a new value to instances of the pointer types <a class="reference internal" href="#ctypes.c_char_p" title="ctypes.c_char_p"><code class="xref py py-class docutils literal notranslate">c_char_p</code></a>,

<a class="reference internal" href="#ctypes.c_wchar_p" title="ctypes.c_wchar_p"><code class="xref py py-class docutils literal notranslate">c_wchar_p</code></a>, and <a class="reference internal" href="#ctypes.c_void_p" title="ctypes.c_void_p"><code class="xref py py-class docutils literal notranslate">c_void_p</code></a> changes the memory location they

point to, not the contents of the memory block (of course not, because Python

bytes objects are immutable):

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> 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

>>>

</pre></div>

</div>

You should be careful, however, not to pass them to functions expecting pointers

to mutable memory. If you need mutable memory blocks, ctypes has a

<a class="reference internal" href="#ctypes.create_string_buffer" title="ctypes.create_string_buffer"><code class="xref py py-func docutils literal notranslate">create_string_buffer()</code></a> function which creates these in various ways. The

current memory block contents can be accessed (or changed) with the <code class="docutils literal notranslate">raw</code>

property; if you want to access it as NUL terminated string, use the <code class="docutils literal notranslate">value</code>

property:

>>> p = create_string_buffer(3) # create a 3 byte buffer, initialized to NUL bytes

>>> print(sizeof(p), repr(p.raw))

3 b'\x00\x00\x00'

>>> p = create_string_buffer(b"Hello") # create a buffer containing a NUL terminated string

6 b'Hello\x00'

>>> print(repr(p.value))

b'Hello'

>>> p = create_string_buffer(b"Hello", 10) # create a 10 byte buffer

10 b'Hello\x00\x00\x00\x00\x00'

>>> p.value = b"Hi"

10 b'Hi\x00lo\x00\x00\x00\x00\x00'

>>>

</pre></div>

</div>

The <a class="reference internal" href="#ctypes.create_string_buffer" title="ctypes.create_string_buffer"><code class="xref py py-func docutils literal notranslate">create_string_buffer()</code></a> function replaces the <code class="xref py py-func docutils literal notranslate">c_buffer()</code> function

(which is still available as an alias), as well as the <code class="xref py py-func docutils literal notranslate">c_string()</code> function

from earlier ctypes releases. To create a mutable memory block containing

unicode characters of the C type <code class="xref c c-type docutils literal notranslate">wchar_t</code> use the

<a class="reference internal" href="#ctypes.create_unicode_buffer" title="ctypes.create_unicode_buffer"><code class="xref py py-func docutils literal notranslate">create_unicode_buffer()</code></a> function.

</div>

<h3>16.16.1.5. Calling functions, continued<a class="headerlink" href="#calling-functions-continued" title="本標題的永久連結">¶</a></h3>

Note that printf prints to the real standard output channel, not to

<a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate">sys.stdout</code></a>, so these examples will only work at the console prompt, not

from within IDLE or PythonWin:

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

ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2

>>>

</pre></div>

</div>

As has been mentioned before, all Python types except integers, strings, and

bytes objects have to be wrapped in their corresponding <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> type, so

that they can be converted to the required C data type:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))

An int 1234, a double 3.140000

31

>>>

</pre></div>

</div>

<h3>16.16.1.6. Calling functions with your own custom data types<a class="headerlink" href="#calling-functions-with-your-own-custom-data-types" title="本標題的永久連結">¶</a></h3>

You can also customize <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> argument conversion to allow instances of

your own classes be used as function arguments. <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> looks for an

<code class="xref py py-attr docutils literal notranslate">_as_parameter_</code> attribute and uses this as the function argument. Of

course, it must be one of integer, string, or bytes:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> class Bottles:

... def __init__(self, number):

... self._as_parameter_ = number

...

>>> bottles = Bottles(42)

42 bottles of beer

19

>>>

</pre></div>

</div>

If you don’t want to store the instance’s data in the <code class="xref py py-attr docutils literal notranslate">_as_parameter_</code>

instance variable, you could define a <a class="reference internal" href="functions.html#property" title="property"><code class="xref py py-class docutils literal notranslate">property</code></a> which makes the

attribute available on request.

</div>

<h3>16.16.1.7. Specifying the required argument types (function prototypes)<a class="headerlink" href="#specifying-the-required-argument-types-function-prototypes" title="本標題的永久連結">¶</a></h3>

It is possible to specify the required argument types of functions exported from

DLLs by setting the <code class="xref py py-attr docutils literal notranslate">argtypes</code> attribute.

<code class="xref py py-attr docutils literal notranslate">argtypes</code> must be a sequence of C data types (the <code class="docutils literal notranslate">printf</code> function is

probably not a good example here, because it takes a variable number and

different types of parameters depending on the format string, on the other hand

this is quite handy to experiment with this feature):

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> 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

>>>

</pre></div>

</div>

Specifying a format protects against incompatible argument types (just as a

prototype for a C function), and tries to convert the arguments to valid types:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> printf(b"%d %d %d", 1, 2, 3)

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

ArgumentError: argument 2: exceptions.TypeError: wrong type

>>> printf(b"%s %d %f\n", b"X", 2, 3)

X 2 3.000000

13

>>>

</pre></div>

</div>

If you have defined your own classes which you pass to function calls, you have

to implement a <code class="xref py py-meth docutils literal notranslate">from_param()</code> class method for them to be able to use them

in the <code class="xref py py-attr docutils literal notranslate">argtypes</code> sequence. The <code class="xref py py-meth docutils literal notranslate">from_param()</code> class method receives

the Python object passed to the function call, it should do a typecheck or

whatever is needed to make sure this object is acceptable, and then return the

object itself, its <code class="xref py py-attr docutils literal notranslate">_as_parameter_</code> attribute, or whatever you want to

pass as the C function argument in this case. Again, the result should be an

integer, string, bytes, a <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> instance, or an object with an

<code class="xref py py-attr docutils literal notranslate">_as_parameter_</code> attribute.

</div>

<h3>16.16.1.8. Return types<a class="headerlink" href="#return-types" title="本標題的永久連結">¶</a></h3>

By default functions are assumed to return the C <code class="xref c c-type docutils literal notranslate">int</code> type. Other

return types can be specified by setting the <code class="xref py py-attr docutils literal notranslate">restype</code> attribute of the

function object.

Here is a more advanced example, it uses the <code class="docutils literal notranslate">strchr</code> function, which expects

a string pointer and a char, and returns a pointer to a string:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> strchr = libc.strchr

>>> strchr(b"abcdef", ord("d"))

8059983

>>> strchr.restype = c_char_p # c_char_p is a pointer to a string

b'def'

>>> print(strchr(b"abcdef", ord("x")))

None

>>>

</pre></div>

</div>

If you want to avoid the <code class="docutils literal notranslate">ord("x")</code> calls above, you can set the

<code class="xref py py-attr docutils literal notranslate">argtypes</code> attribute, and the second argument will be converted from a

single character Python bytes object into a C char:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> strchr.restype = c_char_p

>>> strchr.argtypes = [c_char_p, c_char]

>>> strchr(b"abcdef", b"d")

'def'

>>> strchr(b"abcdef", b"def")

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

ArgumentError: argument 2: exceptions.TypeError: one character string expected

>>> print(strchr(b"abcdef", b"x"))

None

>>> strchr(b"abcdef", b"d")

'def'

>>>

</pre></div>

</div>

You can also use a callable Python object (a function or a class for example) as

the <code class="xref py py-attr docutils literal notranslate">restype</code> attribute, if the foreign function returns an integer. The

callable will be called with the integer the C function returns, and the

result of this call will be used as the result of your function call. This is

useful to check for error return values and automatically raise an exception:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> 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.

>>>

</pre></div>

</div>

<code class="docutils literal notranslate">WinError</code> is a function which will call Windows <code class="docutils literal notranslate">FormatMessage()</code> api to

get the string representation of an error code, and returns an exception.

<code class="docutils literal notranslate">WinError</code> takes an optional error code parameter, if no one is used, it calls

<a class="reference internal" href="#ctypes.GetLastError" title="ctypes.GetLastError"><code class="xref py py-func docutils literal notranslate">GetLastError()</code></a> to retrieve it.

Please note that a much more powerful error checking mechanism is available

through the <code class="xref py py-attr docutils literal notranslate">errcheck</code> attribute; see the reference manual for details.

</div>

<h3>16.16.1.9. Passing pointers (or: passing parameters by reference)<a class="headerlink" href="#passing-pointers-or-passing-parameters-by-reference" title="本標題的永久連結">¶</a></h3>

Sometimes a C api function expects a pointer to a data type as parameter,

probably to write into the corresponding location, or if the data is too large

to be passed by value. This is also known as passing parameters by reference.

<a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> exports the <a class="reference internal" href="#ctypes.byref" title="ctypes.byref"><code class="xref py py-func docutils literal notranslate">byref()</code></a> function which is used to pass parameters

by reference. The same effect can be achieved with the <a class="reference internal" href="#ctypes.pointer" title="ctypes.pointer"><code class="xref py py-func docutils literal notranslate">pointer()</code></a> function,

although <a class="reference internal" href="#ctypes.pointer" title="ctypes.pointer"><code class="xref py py-func docutils literal notranslate">pointer()</code></a> does a lot more work since it constructs a real pointer

object, so it is faster to use <a class="reference internal" href="#ctypes.byref" title="ctypes.byref"><code class="xref py py-func docutils literal notranslate">byref()</code></a> if you don’t need the pointer

object in Python itself:

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

1 3.1400001049 b'Hello'

>>>

</pre></div>

</div>

<h3>16.16.1.10. Structures and unions<a class="headerlink" href="#structures-and-unions" title="本標題的永久連結">¶</a></h3>

Structures and unions must derive from the <a class="reference internal" href="#ctypes.Structure" title="ctypes.Structure"><code class="xref py py-class docutils literal notranslate">Structure</code></a> and <a class="reference internal" href="#ctypes.Union" title="ctypes.Union"><code class="xref py py-class docutils literal notranslate">Union</code></a>

base classes which are defined in the <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> module. Each subclass must

define a <code class="xref py py-attr docutils literal notranslate">_fields_</code> attribute. <code class="xref py py-attr docutils literal notranslate">_fields_</code> must be a list of

2-tuples, containing a field name and a field type.

The field type must be a <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> type like <a class="reference internal" href="#ctypes.c_int" title="ctypes.c_int"><code class="xref py py-class docutils literal notranslate">c_int</code></a>, or any other

derived <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> type: structure, union, array, pointer.

Here is a simple example of a POINT structure, which contains two integers named

x and y, and also shows how to initialize a structure in the constructor:

>>> 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)

0 5

>>> POINT(1, 2, 3)

Traceback (most recent call last):

File "<stdin>", line 1, in <module>

ValueError: too many initializers

>>>

</pre></div>

</div>

You can, however, build much more complicated structures. A structure can

itself contain other structures by using a structure as a field type.

Here is a RECT structure which contains two POINTs named upperleft and

lowerright:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> 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

>>>

</pre></div>

</div>

Nested structures can also be initialized in the constructor in several ways:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> r = RECT(POINT(1, 2), POINT(3, 4))

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

</pre></div>

</div>

Field <a class="reference internal" href="../glossary.html#term-descriptor">descriptor</a>s can be retrieved from the class, they are useful

for debugging because they can provide useful information:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> print(POINT.x)

>>> print(POINT.y)

>>>

</pre></div>

</div>

警告

to functions by value. While this may work on 32-bit x86, it’s not

guaranteed by the library to work in the general case. Unions and

structures with bit-fields should always be passed to functions by pointer.

</div>

<h3>16.16.1.11. Structure/union alignment and byte order<a class="headerlink" href="#structure-union-alignment-and-byte-order" title="本標題的永久連結">¶</a></h3>

By default, Structure and Union fields are aligned in the same way the C

compiler does it. It is possible to override this behavior be specifying a

<code class="xref py py-attr docutils literal notranslate">_pack_</code> class attribute in the subclass definition. This must be set to a

positive integer and specifies the maximum alignment for the fields. This is

what <code class="docutils literal notranslate">#pragma pack(n)</code> also does in MSVC.

structures with non-native byte order, you can use one of the

<a class="reference internal" href="#ctypes.BigEndianStructure" title="ctypes.BigEndianStructure"><code class="xref py py-class docutils literal notranslate">BigEndianStructure</code></a>, <a class="reference internal" href="#ctypes.LittleEndianStructure" title="ctypes.LittleEndianStructure"><code class="xref py py-class docutils literal notranslate">LittleEndianStructure</code></a>,

<code class="xref py py-class docutils literal notranslate">BigEndianUnion</code>, and <code class="xref py py-class docutils literal notranslate">LittleEndianUnion</code> base classes. These

classes cannot contain pointer fields.

</div>

<h3>16.16.1.12. Bit fields in structures and unions<a class="headerlink" href="#bit-fields-in-structures-and-unions" title="本標題的永久連結">¶</a></h3>

It is possible to create structures and unions containing bit fields. Bit fields

are only possible for integer fields, the bit width is specified as the third

item in the <code class="xref py py-attr docutils literal notranslate">_fields_</code> tuples:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> class Int(Structure):

... _fields_ = [("first_16", c_int, 16),

... ("second_16", c_int, 16)]

...

>>> print(Int.first_16)

>>> print(Int.second_16)

>>>

</pre></div>

</div>

<h3>16.16.1.13. Arrays<a class="headerlink" href="#arrays" title="本標題的永久連結">¶</a></h3>

Arrays are sequences, containing a fixed number of instances of the same type.

The recommended way to create array types is by multiplying a data type with a

positive integer:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>TenPointsArrayType = POINT * 10

</pre></div>

</div>

Here is an example of a somewhat artificial data type, a structure containing 4

POINTs among other stuff:

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

>>>

</pre></div>

</div>

Instances are created in the usual way, by calling the class:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>arr = TenPointsArrayType()

for pt in arr:

print(pt.x, pt.y)

</pre></div>

</div>

The above code print a series of <code class="docutils literal notranslate">0 0</code> lines, because the array contents is

initialized to zeros.

Initializers of the correct type can also be specified:

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

>>>

</pre></div>

</div>

<h3>16.16.1.14. Pointers<a class="headerlink" href="#pointers" title="本標題的永久連結">¶</a></h3>

Pointer instances are created by calling the <a class="reference internal" href="#ctypes.pointer" title="ctypes.pointer"><code class="xref py py-func docutils literal notranslate">pointer()</code></a> function on a

<a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> type:

>>> i = c_int(42)

>>> pi = pointer(i)

>>>

</pre></div>

</div>

Pointer instances have a <a class="reference internal" href="#ctypes._Pointer.contents" title="ctypes._Pointer.contents"><code class="xref py py-attr docutils literal notranslate">contents</code></a> attribute which

returns the object to which the pointer points, the <code class="docutils literal notranslate">i</code> object above:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> pi.contents

c_long(42)

>>>

</pre></div>

</div>

Note that <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> does not have OOR (original object return), it constructs a

new, equivalent object each time you retrieve an attribute:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> pi.contents is i

False

>>> pi.contents is pi.contents

False

>>>

</pre></div>

</div>

Assigning another <a class="reference internal" href="#ctypes.c_int" title="ctypes.c_int"><code class="xref py py-class docutils literal notranslate">c_int</code></a> instance to the pointer’s contents attribute

would cause the pointer to point to the memory location where this is stored:

>>> pi.contents = i

>>> pi.contents

c_long(99)

>>>

</pre></div>

</div>

Pointer instances can also be indexed with integers:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> pi[0]

99

>>>

</pre></div>

</div>

Assigning to an integer index changes the pointed to value:

c_long(99)

>>> pi[0] = 22

>>> print(i)

c_long(22)

>>>

</pre></div>

</div>

It is also possible to use indexes different from 0, but you must know what

you’re doing, just as in C: You can access or change arbitrary memory locations.

Generally you only use this feature if you receive a pointer from a C function,

and you know that the pointer actually points to an array instead of a single

item.

Behind the scenes, the <a class="reference internal" href="#ctypes.pointer" title="ctypes.pointer"><code class="xref py py-func docutils literal notranslate">pointer()</code></a> function does more than simply create

pointer instances, it has to create pointer types first. This is done with the

<a class="reference internal" href="#ctypes.POINTER" title="ctypes.POINTER"><code class="xref py py-func docutils literal notranslate">POINTER()</code></a> function, which accepts any <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> type, and returns a

new type:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> PI = POINTER(c_int)

>>> PI

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

>>>

</pre></div>

</div>

Calling the pointer type without an argument creates a <code class="docutils literal notranslate">NULL</code> pointer.

<code class="docutils literal notranslate">NULL</code> pointers have a <code class="docutils literal notranslate">False</code> boolean value:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> null_ptr = POINTER(c_int)()

>>> print(bool(null_ptr))

False

>>>

</pre></div>

</div>

<a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> checks for <code class="docutils literal notranslate">NULL</code> when dereferencing pointers (but dereferencing

invalid non-<code class="docutils literal notranslate">NULL</code> pointers would crash Python):

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> 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

>>>

</pre></div>

</div>

<h3>16.16.1.15. Type conversions<a class="headerlink" href="#type-conversions" title="本標題的永久連結">¶</a></h3>

Usually, ctypes does strict type checking. This means, if you have

<code class="docutils literal notranslate">POINTER(c_int)</code> in the <code class="xref py py-attr docutils literal notranslate">argtypes</code> list of a function or as the type of

a member field in a structure definition, only instances of exactly the same

type are accepted. There are some exceptions to this rule, where ctypes accepts

other objects. For example, you can pass compatible array instances instead of

pointer types. So, for <code class="docutils literal notranslate">POINTER(c_int)</code>, ctypes accepts an array of c_int:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> 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

>>>

</pre></div>

</div>

In addition, if a function argument is explicitly declared to be a pointer type

(such as <code class="docutils literal notranslate">POINTER(c_int)</code>) in <code class="xref py py-attr docutils literal notranslate">argtypes</code>, an object of the pointed

type (<code class="docutils literal notranslate">c_int</code> in this case) can be passed to the function. ctypes will apply

the required <a class="reference internal" href="#ctypes.byref" title="ctypes.byref"><code class="xref py py-func docutils literal notranslate">byref()</code></a> conversion in this case automatically.

To set a POINTER type field to <code class="docutils literal notranslate">NULL</code>, you can assign <code class="docutils literal notranslate">None</code>:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> bar.values = None

>>>

</pre></div>

</div>

Sometimes you have instances of incompatible types. In C, you can cast one type

into another type. <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a> provides a <a class="reference internal" href="#ctypes.cast" title="ctypes.cast"><code class="xref py py-func docutils literal notranslate">cast()</code></a> function which can be

used in the same way. The <code class="docutils literal notranslate">Bar</code> structure defined above accepts

<code class="docutils literal notranslate">POINTER(c_int)</code> pointers or <a class="reference internal" href="#ctypes.c_int" title="ctypes.c_int"><code class="xref py py-class docutils literal notranslate">c_int</code></a> arrays for its <code class="docutils literal notranslate">values</code> field,

but not instances of other types:

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

>>>

</pre></div>

</div>

For these cases, the <a class="reference internal" href="#ctypes.cast" title="ctypes.cast"><code class="xref py py-func docutils literal notranslate">cast()</code></a> function is handy.

The <a class="reference internal" href="#ctypes.cast" title="ctypes.cast"><code class="xref py py-func docutils literal notranslate">cast()</code></a> function can be used to cast a ctypes instance into a pointer

to a different ctypes data type. <a class="reference internal" href="#ctypes.cast" title="ctypes.cast"><code class="xref py py-func docutils literal notranslate">cast()</code></a> takes two parameters, a ctypes

object that is or can be converted to a pointer of some kind, and a ctypes

pointer type. It returns an instance of the second argument, which references

the same memory block as the first argument:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> a = (c_byte * 4)()

>>> cast(a, POINTER(c_int))

<ctypes.LP_c_long object at ...>

>>>

</pre></div>

</div>

So, <a class="reference internal" href="#ctypes.cast" title="ctypes.cast"><code class="xref py py-func docutils literal notranslate">cast()</code></a> can be used to assign to the <code class="docutils literal notranslate">values</code> field of <code class="docutils literal notranslate">Bar</code> the

structure:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> bar = Bar()

>>> bar.values = cast((c_byte * 4)(), POINTER(c_int))

>>> print(bar.values[0])

0

>>>

</pre></div>

</div>

<h3>16.16.1.16. Incomplete Types<a class="headerlink" href="#incomplete-types" title="本標題的永久連結">¶</a></h3>

Incomplete Types are structures, unions or arrays whose members are not yet

specified. In C, they are specified by forward declarations, which are defined

later:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>struct cell; /* forward declaration */

struct cell {

char *name;

struct cell *next;

};

</pre></div>

</div>

The straightforward translation into ctypes code would be this, but it does not

work:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> 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

>>>

</pre></div>

</div>

because the new <code class="docutils literal notranslate">class cell</code> is not available in the class statement itself.

In <a class="reference internal" href="#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate">ctypes</code></a>, we can define the <code class="docutils literal notranslate">cell</code> class and set the <code class="xref py py-attr docutils literal notranslate">_fields_</code>

attribute later, after the class statement:

>>> class cell(Structure):

... pass

...

>>> cell._fields_ = [("name", c_char_p),

>>>

</pre></div>

</div>

Lets try it. We create two instances of <code class="docutils literal notranslate">cell</code>, and let them point to each

other, and finally follow the pointer chain a few times:

<div class="highlight-python3 notranslate"><div class="highlight"><pre>>>> c1 = cell()

>>> c1.name = "foo"

>>> c2 = cell()

>>> c2.name = "bar"

>>> c1.next = pointer(c2)

>>> c2.next = pointer(c1)

>>> p = c1

... print(p.name, end=" ")

... p = p.next[0]

...

foo bar foo bar foo bar foo bar

>>>

</pre></div>

</div>

<h3>16.16.1.17. Callback functions<a class="headerlink" href="#callback-functions" title="本標題的永久連結">¶</a></h3>

These are sometimes called callback functions.

First, you must create a class for the callback function. The class knows the

calling convention, the return type, and the number and types of arguments this

function will receive.

The <a class="reference internal" href="#ctypes.CFUNCTYPE" title="ctypes.CFUNCTYPE"><code class="xref py py-func docutils literal notranslate">CFUNCTYPE()</code></a> factory function creates types for callback functions

using the <code class="docutils literal notranslate">cdecl</code> calling convention. On Windows, the <a class="reference internal" href="#ctypes.WINFUNCTYPE" title="ctypes.WINFUNCTYPE"><code class="xref py py-func docutils literal notranslate">WINFUNCTYPE()</code></a>

factory function creates types for callback functions using the <code class="docutils literal notranslate">stdcall</code>

calling convention.

Both of these factory functions are called with the result type as first

argument, and the callback functions expected argument types as the remaining

arguments.

I will present an example here which uses the standard C library’s

<code class="xref c c-func docutils literal notranslate">qsort()</code> function, that is used to sort items with the help of a callback

function. <code class="xref c c-func docutils literal notranslate">qsort()</code> will be used to sort an array of integers:

View remainder of file in raw view

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

ctypes.html

Latest commit

History

ctypes.html

File metadata and controls