Update main POD with TODOs
[perl-ctypes:perl-ctypes.git] / lib / Ctypes.pm
1 package Ctypes;
2 use strict;
3 use warnings;
4
5 =pod
6
7 =encoding utf8
8
9 =head1 NAME
10
11 Ctypes - Call and wrap C libraries and functions from Perl, using Perl
12
13 =head1 VERSION
14
15 Version 0.003
16
17 =cut
18
19 our $VERSION = '0.003';
20
21 use AutoLoader;
22 use Carp;
23 use Config;
24 use Ctypes::Type;
25 use Ctypes::Type::Struct;
26 use Ctypes::Type::Union;
27 use DynaLoader;
28 use File::Spec;
29 use Getopt::Long;
30 use Scalar::Util qw|blessed looks_like_number|;
31
32 require Exporter;
33 our @ISA = qw(Exporter);
34 our @EXPORT = ( qw|CDLL WinDLL OleDLL PerlDLL
35                    WINFUNCTYPE CFUNCTYPE PERLFUNCTYPE
36                    POINTER WinError byref is_ctypes_compat
37                    Array Pointer Struct Union USE_PERLTYPES
38                   |, @Ctypes::Type::_allnames );
39 our @EXPORT_OK = qw|PERL|;
40
41 require XSLoader;
42 XSLoader::load('Ctypes', $VERSION);
43
44 =head1 SYNOPSIS
45
46     use Ctypes;
47
48     my $lib  = CDLL->LoadLibrary("-lm");
49     my $func = $lib->sqrt;
50     my $ret = $lib->sqrt(16.0); # on Windows only
51     # non-windows
52     my $ret = $lib->sqrt({sig=>"cdd"},16.0);
53
54     # bare
55     my $ret  = Ctypes::call( $func, 'cdd', 16.0  );
56     print $ret; # 4
57
58     # which is the same as:
59     use DynaLoader;
60     my $lib =  DynaLoader::dl_load_file( DynaLoader::dl_findfile( "-lm" ));
61     my $func = Dynaloader::dl_find_symbol( $lib, 'sqrt' );
62     my $ret  = Ctypes::call( $func, 'cdd', 16.0  );
63
64 =head1 ABSTRACT
65
66 Ctypes is the Perl equivalent to the Python ctypes FFI library, using
67 libffi. It provides C compatible data types, and allows one to call
68 functions in dlls/shared libraries.
69
70 =head1 DESCRIPTION
71
72 Ctypes is designed to let module authors wrap native C libraries in a pure Perly
73 (or Python) way. Authors can benefit by not having to deal with any XS or C
74 code. Users benefit from not having to have a compiler properly installed and
75 configured - they simply download the necessary binaries and run the
76 Ctypes-based Perl modules written against them.
77
78 The module should also be as useful for the admin, scientist or general
79 datamangler who wants to quickly script together a couple of functions
80 from different native libraries as for the Perl module author who wants
81 to expose the full functionality of a large C/C++ project.
82
83 =head2 Typecodes
84
85 Here are the currently supported low-level signature typecode characters, with
86 the matching Ctypes and perl-style packcodes.
87 As you can see, there is some overlap with Perl's L<pack|perlfunc/pack> notation,
88 they're not identical (v, h, H), and offer a wider range of types as on the 
89 python ctypes typecodes (s,w,z,...).
90
91 With C<use Ctypes 'PERL'>, you can demand Perl's L<pack|perlfunc/pack> notation.
92
93 Typecode: Ctype                  perl Packcode
94   'v': void
95   'b': c_byte (signed char)      c
96   'B': c_ubyte (unsigned char)   C
97   'c': c_char (signed char)      c
98   'C': c_uchar (unsigned char)   C
99
100   'h': c_short (signed short)    s
101   'H': c_ushort (unsigned short) S
102   'i': c_int (signed int)        i
103   'I': c_uint (unsigned int)     I
104   'l': c_long (signed long)      l
105   'L': c_ulong (unsigned long)   L
106   'f': c_float                   f
107   'd': c_double                  d
108   'g': c_longdouble              D
109   'q': c_longlong                q
110   'Q': c_ulonglong               Q
111
112   'Z': c_char_p (ASCIIZ string)  A?
113   'w': c_wchar                   U
114   'z': c_wchar_p                 U*
115   'X': c_bstr (2byte string)     a?
116
117 =cut
118
119 our $USE_PERLTYPES = 0; # import arg -PERL: full python ctypes types,
120                         # or just the simplier perl pack-style types
121 sub USE_PERLTYPES { $USE_PERLTYPES }
122 sub PERL {
123   $USE_PERLTYPES = 1;
124   #eval q|sub Ctypes::Type::c_short::typecode{'s'}; 
125   #       sub Ctypes::Type::c_ushort::typecode{'S'};
126   #       sub Ctypes::Type::c_longdouble::typecode{'D'}
127   #      |;
128 }
129
130 =head1 FUNCTIONS
131
132 =over
133
134 =item call ADDR, SIG, [ ARGS ... ]
135
136 Call the external function via C<libffi> at the address specified by B<ADDR>,
137 with the signature specified by B<SIG>, optional B<ARGS>, and return a value.
138
139 C<Ctypes::call> is modelled after the C<call> function found in
140 L<FFI.pm|FFI>: it's the low-level, bare bones access to Ctypes'
141 capabilities. Most of the time you'll probably prefer the
142 abstractions provided by L<Ctypes::Function>.
143
144 I<SIG> is the signature string. The first character specifies the
145 calling-convention: B<s> for stdcall, B<c> for cdecl (or 64-bit fastcall).
146 The second character specifies the B<typecode> for the return type
147 of the function, and the subsequent characters specify the argument types.
148
149 L<Typecodes> are single character designations for various C data types.
150 They're similar in concept to the codes used by Perl's
151 L<pack|perlfunc/pack> and L<unpack|perlfunc/unpack> functions, but they
152 are B<not> the same codes!
153
154 I<ADDR> is the function address, the return value of L<find_function> or
155 L<DynaLoader::dl_find_symbol>.
156
157 I<ARGS> are the optional arguments for the external function. The types
158 are converted as specified by sig[2..].
159
160 =cut
161
162 sub call {
163   my $func = shift;
164   my $sig = shift;
165   my @args = @_;
166   my @argtypes = ();
167   @argtypes = split( //, substr( $sig, 2 ) ) if length $sig > 2;
168   for(my $i=0 ; $i<=$#args ; $i++) {
169     # valid ffi sizecode's
170     if( $argtypes[$i] =~ /[dDfFiIjJlLnNqQsSvV]/ and
171         not looks_like_number( $args[$i] ) ) {
172       $args[$i] = $args[$i]->value()
173         or die "$i-th argument $args[$i] is no number";
174       die "$i-th argument $args[$i] is no number"
175         unless looks_like_number( $args[$i] );
176     }
177   }
178   return _call( $func, $sig, @args );
179 }
180
181 =item Array I<LIST>
182
183 =item Array I<TYPE>, I<ARRAYREF>
184
185 Create a L<Ctypes::Type::Array> object. LIST and ARRAYREF can contain
186 Ctypes objects, or a Perl natives.
187
188 If the latter, Ctypes will try to choose the smallest appropriate C
189 type and create Ctypes objects out of the Perl natives for you. You
190 can find out which type it chose afterwards by calling the C<member_type>
191 accessor method on the Array object.
192
193 If you want to specify the data type of the array, you can do so by
194 passing a Ctypes type as the first parameter, and the contents in an
195 array reference as the second. Naturally, your data must be compatible
196 with the type specified, otherwise you'll get an error from the a
197 C<Ctypes::Type::Simple> constructor.
198
199 And of course, in C(types), all your array input has to be of the same
200 type.
201
202 See L<Ctypes::Type::Array> for more detailed documentation.
203
204 =cut
205
206 sub Array {
207   return Ctypes::Type::Array->new(@_);
208 }
209
210 =item Pointer OBJECT
211
212 =item Pointer TYPE, OBJECT
213
214 Create a L<Ctypes::Type::Pointer> object. OBJECT must be a Ctypes object.
215 See the relevant documentation for more information.
216
217 =cut
218
219 sub Pointer {
220   return Ctypes::Type::Pointer->new(@_);
221 }
222
223 =item Struct
224
225 Create a L<Ctypes::Type::Struct> object. Basing new classes on Struct
226 may also often be more useful than subclassing other Types. See the
227 relevant documentation for more information.
228
229 =cut
230
231 sub Struct {
232   return Ctypes::Type::Struct->new(@_);
233 }
234
235 =item Union
236
237 Create and return a L<Ctypes::Type::Union> object. See the documentation
238 for L<Ctypes::Type::Union> and L<Ctypes::Type::Struct> for information on
239 instantiation etc.
240
241 =cut
242
243 sub Union {
244   return Ctypes::Type::Union->new(@_);
245 }
246
247 =item load_library (lib, [mode])
248
249 Searches the dll/so loadpath for the given library, architecture dependently.
250
251 The lib argument is either part of a filename (e.g. "kernel32") with
252 platform specific path and extension defaults,
253 a full pathname to the shared library
254 or the same as for L<DynaLoader::dl_findfile>:
255 "-llib" or "-Lpath -llib", with -L for the optional path.
256
257 Returns a libraryhandle, to be used for find_function.
258 Uses L<Ctypes::Util::find_library> to find the path.
259 See also the L<LoadLibrary> method for a DLL object,
260 which also returns a handle and L<DynaLoader::dl_load_file>.
261
262 With C<mode> optional dynaloader args can be specified:
263
264 =over
265
266 =item RTLD_GLOBAL
267
268 Flag to use as mode parameter. On platforms where this flag is not
269 available, it is defined as the integer zero.
270
271 =item RTLD_LOCAL
272
273 Flag to use as mode parameter. On platforms where this is not
274 available, it is the same as RTLD_GLOBAL.
275
276 =item DEFAULT_MODE
277
278 The default mode which is used to load shared libraries. On OSX 10.3,
279  this is RTLD_GLOBAL, otherwise it is the same as RTLD_LOCAL.
280
281 =back
282
283 =cut
284
285 sub load_library($;@) {
286   my $path = Ctypes::Util::find_library( shift, @_ );
287   # XXX This might trigger a Windows MessageBox on error.
288   # We might want to suppress it as done in cygwin.
289   return DynaLoader::dl_load_file($path, @_) if $path;
290 }
291
292 =item CDLL (library, [mode])
293
294 Searches the library search path for the given name, and
295 returns a library object which defaults to the C<cdecl> ABI, with
296 default restype C<i>.
297
298 For B<mode> see L<load_library>.
299
300 =cut
301
302 sub CDLL {
303   return Ctypes::CDLL->new( @_ );
304 }
305
306 =item WinDLL (library, [mode])
307
308 Windows only: Searches the library search path for the given name, and
309 returns a library object which defaults to the C<stdcall> ABI,
310 with default restype C<i>.
311
312 For B<mode> see L<load_library>.
313
314 =cut
315
316 sub WinDLL {
317   return Ctypes::WinDLL->new( @_ );
318 }
319
320 =item OleDLL (library, [mode])
321
322 Windows only: Objects representing loaded shared libraries, functions
323 in these libraries use the C<stdcall> calling convention, and are assumed
324 to return the windows specific C<HRESULT> code. HRESULT values contain
325 information specifying whether the function call failed or succeeded,
326 together with additional error code. If the return value signals a
327 failure, a L<WindowsError> is automatically raised.
328
329 For B<mode> see L<load_library>.
330
331 =cut
332
333 sub OleDLL {
334   return Ctypes::OleDLL->new( @_ );
335 }
336
337 =item PerlDLL (library)
338
339 Instances of this class behave like CDLL instances, except that the
340 Perl XS library is not released during the function call, and after
341 the function execution the Perl error flag is checked. If the error
342 flag is set, a Perl exception is raised.  Thus, this is only useful
343 to call Perl XS api functions directly.
344
345 =cut
346
347 sub PerlDLL() {
348   return Ctypes::PerlDLL->new( @_ );
349 }
350
351 =item CFUNCTYPE (restype, argtypes...)
352
353 The returned L<C function prototype|Ctypes::FuncProto::C> creates a
354 function that use the standard C calling convention. The function will
355 release the library during the call.
356
357 C<restype> and C<argtypes> are L<Ctype::Type> objects, such as C<c_int>,
358 C<c_void_p>, C<c_char_p> etc..
359
360 =item WINFUNCTYPE (restype, argtypes...)
361
362 Windows only: The returned L<Windows function prototype|Ctypes::FuncProto::Win>
363 creates a function that use the C<stdcall> calling convention.
364 The function will release the library during the call.
365
366 B<SYNOPSIS>
367
368   my $prototype  = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT);
369   my $paramflags = [[1, "hwnd", 0], [1, "text", "Hi"],
370                    [1, "caption", undef], [1, "flags", 0]];
371   my $MessageBox = $prototype->(("MessageBoxA", WinDLL->user32), $paramflags);
372   $MessageBox->({text=>"Spam, spam, spam")});
373
374 =item PERLFUNCTYPE (restype, argtypes...)
375
376 The returned function prototype creates functions that use the Perl XS
377 calling convention. The function will not release the library during
378 the call.
379
380 =cut
381
382 sub WINFUNCTYPE {
383   use Ctypes::FuncProto;
384   return Ctypes::FuncProto::Win->new( @_ );
385 }
386 sub CFUNCTYPE {
387   use Ctypes::FuncProto;
388   return Ctypes::FuncProto::C->new( @_ );
389 }
390 sub PERLFUNCTYPE {
391   use Ctypes::FuncProto;
392   return Ctypes::FuncProto::Perl->new( @_ );
393 }
394
395 =item callback (<perlfunc>, <restype>, <argtypes>)
396
397 Creates a callable, an external function which calls back into perl,
398 specified by the signature and a reference to a perl sub.
399
400 B<perlfunc> is a named (or anonymous?) subroutine reference.
401 B<restype> is a single character string representing the return type,
402 and B<argtypes> is a multi-character string representing the argument
403 types the function will receive from C. All types are represented
404 in L<typecode|/"call SIG, ADDR, [ ARGS ... ]"> format.
405
406 B<Note> that the interface for C<Callback->new()> will be updated
407 to be more consistent with C<Function->new()>.
408
409 =cut
410
411 sub callback($$$) {
412   return Ctypes::Callback->new( @_ );
413 }
414
415 =back
416
417 =head1 Ctypes::DLL
418
419 Define objects for shared libraries and its abi.
420
421 Subclasses are B<CDLL>, B<WinDLL>, B<OleDLL> and B<PerlDLL>, returning objects
422 defining the path, handle, restype and abi of the found shared library.
423
424 Submethods are B<LoadLibrary> and the functions and variables inside the library.
425
426 Properties are C<_name>, C<_path>, C<_abi>, C<_handle>.
427
428   $lib = CDLL->msvcrt;
429
430 is the same as C<CDLL->new("msvcrt")>,
431 but C<CDLL->libc> should be used for cross-platform compat.
432
433   $func = CDLL->c->toupper;
434
435 returns the function for the libc function C<toupper()>,
436 on Windows and Posix.
437
438 Functions within libraries can be declared.
439 or called directly.
440
441   $ret = CDLL->libc->toupper({sig => "cii"})->ord("y");
442
443 =cut
444
445 package Ctypes::DLL;
446 use strict;
447 use warnings;
448 use Ctypes;
449 use Ctypes::Function;
450 use Carp;
451
452 # This AUTOLOAD is used to define the dll/soname for the library,
453 # or access a function in the library.
454 # $lib = CDLL->msvcrt; $func = CDLL->msvcrt->toupper;
455 # Indexed with CDLL->msvcrt[0] (tied array?) on windows only
456 # or named with WinDLL->kernel32->GetModuleHandle({sig=>"sll"})->(32)
457 sub AUTOLOAD {
458   my $name;
459   our $AUTOLOAD;
460   ($name = $AUTOLOAD) =~ s/.*:://;
461   return if $name eq 'DESTROY';
462   # property
463   if ($name =~ /^_(abi|handle|path|name)$/) {
464     *$AUTOLOAD = sub {
465       my $self = shift;
466       # only _abi is setable
467       if ($name eq 'abi') {
468         if (@_) {
469           return $self->{$name} = $_[0];
470         }
471         if (defined $self->{$name} ) {
472           return $self->{$name};
473         } else { return undef; }
474       } else {
475         warn("$name not setable") if @_;
476         if (defined $self->{$name} ) {
477           return $self->{$name};
478         } else { return undef; }
479       }
480       goto &$AUTOLOAD;
481     }
482   }
483   if (@_) {
484     # ->library
485     my $lib = shift;
486     # library not yet loaded?
487     if (ref($lib) =~ /^Ctypes::(|C|Win|Ole|Perl)DLL$/ and !$lib->{_handle}) {
488       $lib->LoadLibrary($name)
489         or croak "LoadLibrary($name) failed";
490       return $lib;
491     } else { # name is a ->function
492       my $props = { lib => $lib->{_handle},
493                     abi => $lib->{_abi},
494                     restype => $lib->{_restype},
495                     name => $name };
496       if (@_ and ref $_[0] eq 'HASH') { # declare the sig or restype via HASHREF
497         my $arg = shift;
498         $props->{sig} = $arg->{sig} if $arg->{sig};
499         $props->{restype} = $arg->{restype} if $arg->{restype};
500         $props->{argtypes} = $arg->{argtypes} if $arg->{argtypes};
501       }
502       return Ctypes::Function->new($props, @_);
503     }
504   } else {
505     my $lib = Ctypes::load_library($name)
506       or croak "Ctypes::load_library($name) failed";
507     return $lib; # scalar handle only?
508   }
509 }
510
511 =head1 LoadLibrary (name [mode])
512
513 A DLL method which loads the given shared library,
514 and on success sets the new object properties path and handle,
515 and returns the library handle.
516
517 =cut
518
519 sub LoadLibrary($;@) {
520   my $self = shift;
521   my $path = $self->{_path};
522   $self->{_name} = shift;
523   $self->{_abi} = ref $self eq 'Ctypes::CDLL' ? 'c' : 's';
524   $path = Ctypes::Util::find_library( $self->{_name} ) unless $path;
525   $self->{_handle} = DynaLoader::dl_load_file($path, @_) if $path;
526   $self->{_path} = $path if $self->{_handle};
527   return $self->{_handle};
528 }
529
530 =head1 CDLL
531
532   $lib = CDLL->msvcrt;
533
534 is a fancy name for Ctypes::CDLL->new("msvcrt").
535 Note that you should really use the platform compatible
536 CDLL->c for the current libc, which can be any msvcrtxx.dll
537
538   $func = CDLL->msvcrt->toupper;
539
540 returns the function for the Windows libc function toupper,
541 but this function cannot be called, since the sig is missing.
542 It only checks if the symbol is define inside the library.
543 You can add the sig later, as in
544
545   $func->{sig} = 'cii';
546
547 or call the function like
548
549   $ret = CDLL->msvcrt->toupper({sig=>"cii"})->(ord("y"));
550
551 On windows you can also define and call functions by their
552 ordinal in the library.
553
554 Define:
555
556   $func = CDLL->kernel32[1];
557
558 Call:
559
560   $ret = CDLL->kernel32[1]->();
561
562 =head1 WinDLL
563
564   $lib = WinDLL->kernel32;
565
566 Windows only: Returns a library object for the Windows F<kernel32.dll>.
567
568 =head1 OleDLL
569
570   $lib = OleDLL->mshtml;
571
572 Windows only.
573
574 =cut
575
576 package Ctypes::CDLL;
577 use strict;
578 use warnings;
579 use Ctypes;
580 our @ISA = qw(Ctypes::DLL);
581 use Carp;
582
583 sub new {
584   my $class = shift;
585   my $props = { _abi => 'c', _restype => 'i' };
586   if (@_) {
587     $props->{_path} = Ctypes::Util::find_library(shift);
588     $props->{_handle} = Ctypes::load_library($props->{_path});
589   }
590   return bless $props, $class;
591 }
592
593 #our ($libc, $libm);
594 #sub libc {
595 #  return $libc if $libc;
596 #  $libc = load_library("c");
597 #}
598 #sub libm {
599 #  return $libm if $libm;
600 #  $libm = load_library("m");
601 #}
602
603 package Ctypes::WinDLL;
604 use strict;
605 use warnings;
606 our @ISA = qw(Ctypes::DLL);
607
608 sub new {
609   my $class = shift;
610   my $props = { _abi => 's', _restype => 'i' };
611   if (@_) {
612     $props->{_path} = Ctypes::Util::find_library(shift);
613     $props->{_handle} = Ctypes::load_library($props->{_path});
614   }
615   return bless $props, $class;
616 }
617
618 package Ctypes::OleDLL;
619 use strict;
620 use warnings;
621 use Ctypes;
622 our @ISA = qw(Ctypes::DLL);
623
624 sub new {
625   my $class = shift;
626   my $props = { abi => 's', _restype => 'p', _oledll => 1 };
627   if (@_) {
628     $props->{_path} = Ctypes::Util::find_library(shift);
629     $props->{_handle} = Ctypes::load_library($props->{_path});
630   }
631   return bless $props, $class;
632 }
633
634 package Ctypes::PerlDLL;
635 use strict;
636 use warnings;
637 our @ISA = qw(Ctypes::DLL);
638
639 sub new {
640   my $class = shift;
641   my $name = shift;
642   # TODO: name may be split into subpackages: PerlDLL->new("C::DynaLib")
643   my $props = { _abi => 'c', _restype => 'i', _name => $name, _perldll => 1 };
644   die "TODO perl xs library search";
645   $name =~ s/::/\//g;
646   #$props->{_path} = $Config{...}.$name.$Config{soext};
647   my $self = bless $props, $class;
648   $self->LoadLibrary($props->{_path});
649 }
650
651 package Ctypes;
652
653 =over
654
655 =item find_function (libraryhandle, functionname)
656
657 Returns the function address of the exported function within the shared library.
658 libraryhandle is the return value of find_library or DynaLoader::dl_load_file.
659
660 =cut
661
662 sub find_function($$) {
663   return DynaLoader::dl_find_symbol( shift, shift );
664 }
665
666 =item load_error ()
667
668 Returns the error description of the last L<load_library> call,
669 via L<DynaLoader::dl_error>.
670
671 =cut
672
673 sub load_error() {
674   return DynaLoader::dl_error();
675 }
676
677 =item addressof (obj)
678
679 Returns the address of the memory buffer as integer. C<obj> must be an
680 instance of a ctypes type.
681
682 =cut
683
684 sub addressof($) {
685   my $obj = shift;
686   $obj->isa("Ctypes::Type")
687     or die "addressof(".ref $obj.") not a Ctypes::Type";
688   return $obj->{address};
689 }
690
691 =item alignment(obj_or_type)
692
693 Returns the alignment requirements of a Ctypes type.
694 C<obj_or_type> must be a Ctypes type or instance.
695
696 =cut
697
698 sub alignment($) {
699   my $obj = shift;
700   $obj->isa("Ctypes::Type")
701     or die "alignment(".ref $obj.") not a Ctypes::Type or instance";
702   return $obj->{alignment};
703 }
704
705 =item byref(obj)
706
707 Returns a light-weight pointer to C<obj>, which must be an instance of a
708 Ctypes type. The returned object can only be used as a foreign
709 function call parameter. It behaves similar to C<pointer(obj)>, but the
710 construction is a lot faster.
711
712 =cut
713
714 sub byref {
715   return \$_[0];
716 }
717
718 =item is_ctypes_compat(obj)
719
720 Returns 1 if C<obj> is Ctypes compatible - that is, it has a
721 C<_as_param_>, C<_update_> and C<_typecode_> methods, and the value returned
722 by C<_typecode_> is valid. Returns C<undef> otherwise.
723
724 =cut
725
726 sub is_ctypes_compat (\$) {
727   if( blessed($_[0]),
728       and $_[0]->can('_as_param_')
729       and $_[0]->can('_update_')
730       and $_[0]->can('typecode')
731     ) {
732     #my $types = CTypes::Type::_types;
733     #return undef unless exists $_types->{$_[0]->typecode};
734     eval{ Ctypes::sizeof($_[0]->sizecode) };
735     if( !$@ ) {
736       return 1;
737     }
738   }
739   return undef;
740 }
741
742 =item cast(obj, type)
743
744 This function is similar to the cast operator in C. It returns a new
745 instance of type which points to the same memory block as C<obj>. C<type>
746 must be a pointer type, and obj must be an object that can be
747 interpreted as a pointer.
748
749 =item create_string_buffer(init_or_size[, size])
750
751 This function creates a mutable character buffer. The returned object
752 is a Ctypes array of C<c_char>.
753
754 C<init_or_size> must be an integer which specifies the size of the array,
755 or a string which will be used to initialize the array items.
756
757 If a string is specified as first argument, the buffer is made one
758 item larger than the length of the string so that the last element in
759 the array is a NUL termination character. An integer can be passed as
760 second argument which allows to specify the size of the array if the
761 length of the string should not be used.
762
763 If the first parameter is a unicode string, it is converted into an
764 8-bit string according to Ctypes conversion rules.
765
766 =item create_unicode_buffer(init_or_size[, size])
767
768 This function creates a mutable unicode character buffer. The returned
769 object is a Ctypes array of C<c_wchar>.
770
771 C<init_or_size> must be an integer which specifies the size of the array,
772 or a unicode string which will be used to initialize the array items.
773
774 If a unicode string is specified as first argument, the buffer is made
775 one item larger than the length of the string so that the last element
776 in the array is a NUL termination character. An integer can be passed
777 as second argument which allows to specify the size of the array if
778 the length of the string should not be used.
779
780 If the first parameter is a 8-bit string, it is converted into an
781 unicode string according to Ctypes conversion rules.
782
783 =item DllCanUnloadNow()
784
785 Windows only: This function is a hook which allows to implement
786 in-process COM servers with Ctypes. It is called from the
787 C<DllCanUnloadNow> function that the Ctypes XS extension dll exports.
788
789 =item DllGetClassObject()
790
791 Windows only: This function is a hook which allows to implement
792 in-process COM servers with ctypes. It is called from the
793 C<DllGetClassObject> function that the Ctypes XS extension dll exports.
794
795 =item FormatError([code])
796
797 Windows only: Returns a textual description of the error code. If no
798 error code is specified, the last error code is used by calling the
799 Windows API function C<GetLastError>.
800
801 =item GetLastError()
802
803 Windows only: Returns the last error code set by Windows in the calling thread.
804
805 =item memmove(dst, src, count)
806
807 Same as the standard C memmove library function: copies count bytes from C<src>
808 to C<dst>. C<dst> and C<src> must be integers or Ctypes instances that can be
809 converted to pointers.
810
811 =item memset(dst, c, count)
812
813 Same as the standard C memset library function: fills the memory block
814 at address C<dst> with C<count> bytes of value C<c>. C<dst> must be an integer
815 specifying an address, or a Ctypes instance.
816
817 =item POINTER(type)
818
819 This factory function creates and returns a new Ctypes pointer
820 type. Pointer types are cached an reused internally, so calling this
821 function repeatedly is cheap. C<type> must be a Ctypes type.
822
823 =item pointer(obj)
824
825 This function creates a new pointer instance, pointing to C<obj>. The
826 returned object is of the type C<POINTER(type(obj))>.
827
828 Note: If you just want to pass a pointer to an object to a foreign
829 function call, you should use C<byref(obj)> which is much faster.
830
831 =item resize(obj, size)
832
833 This function resizes the internal memory buffer of C<obj>, which must be
834 an instance of a Ctypes type. It is not possible to make the buffer
835 smaller than the native size of the objects type, as given by
836 C<sizeof(type(obj))>, but it is possible to enlarge the buffer.
837
838 =item set_conversion_mode(encoding, errors)
839
840 This function sets the rules that Ctypes objects use when converting
841 between 8-bit strings and unicode strings. encoding must be a string
842 specifying an encoding, like 'utf-8' or 'mbcs', errors must be a
843 string specifying the error handling on encoding/decoding
844 errors. Examples of possible values are "strict", "replace", or
845 "ignore".
846
847 C<set_conversion_mode> returns a 2-tuple containing the previous
848 conversion rules. On Windows, the initial conversion rules are
849 ('mbcs', 'ignore'), on other systems ('ascii', 'strict').
850
851 =item sizeof(obj_or_type)
852
853 Returns the size in bytes of a Ctypes type or instance memory
854 buffer. Does the same as the C C<sizeof()> function.
855
856 =item string_at(address[, size])
857
858 This function returns the string starting at memory address
859 C<address>. If C<size> is specified, it is used as size, otherwise the
860 string is assumed to be zero-terminated.
861
862 =item WinError( { code=>undef, descr=>undef } )
863
864 Windows only: this function is probably the worst-named thing in
865 Ctypes. It creates an instance of L<WindowsError>.
866
867 If B<code> is not specified, L<GetLastError> is called to determine the
868 error code. If B<descr> is not spcified, FormatError is called to get
869 a textual description of the error.
870
871 =item wstring_at(address [, size])
872
873 This function returns the wide character string starting at memory
874 address C<address> as unicode string. If C<size> is specified, it is used as
875 the number of characters of the string, otherwise the string is
876 assumed to be zero-terminated.
877
878 =back
879
880 =head1 API Comparison
881
882 Ctypes:
883
884     my $function = Ctypes::Function->new( 'libc', 'sqrt', 'sig' );
885
886 P5NCI:
887
888     my $function  = P5NCI::load_func( $library, 'func', 'sig' );
889     my $double_double = $lib->load_function( 'func', 'sig' );
890
891 C::DynaLib:
892
893     $func = $lib->DeclareSub( $symbol_name[, $return_type [, @arg_types] ] );
894     $func = DeclareSub( $function_pointer[, $return_type [, @arg_types] ] );
895
896 FFI.pm:
897
898     $lib = FFI::Library->new("mylib");
899     $fn = $lib->function("fn", "signature");
900
901 =head1 TODO
902
903 =head2 General
904
905 Basically you can help porting the mess from the old over-architectured OO layout 
906 to the new class layout.
907
908   done: Simple and partially Pointer
909   todo: Array, Struct, Field, Union, and fix the "not so simple" Simple types.
910
911 See http://gitorious.org/perl-ctypes/perl-ctypes/commits/classify
912
913 =over
914
915 =item * Convert to using actual C-space storage for basic types
916
917 Python has an abstract base class with some basic methods, and the same
918 C structure underlying all C type classes.
919
920     struct tagCDataObject {
921        (PyObject_HEAD               /* Standard Python object fields */)
922
923         char *b_ptr;                /* pointer to memory block */
924         Py_ssize_t b_size;          /* size of memory block in bytes */
925         Py_ssize_t b_length;        /* number of fields of this object */
926         Py_ssize_t b_index;         /* index of this object into the base
927                                        objects b_object list */
928
929         int b_needsfree;            /* does the object own its memory block? */
930         CDataObject *b_base;        /* pointer to base object or NULL */
931         PyObject *b_objects;        /* references we need to keep */
932         union value b_value;        /* a small default buffer */
933     }
934
935 =item * Expand range of basic Types (see below for list)
936
937 =over
938
939 =item * Tests for all basic Types
940
941 =back
942
943 =item * Raise general code quality to encourage contributions
944
945 =over
946
947 =item * More consistent method names
948
949 =item * Resolve or properly document all XXX's and ???'s
950
951 =back
952
953 =item * Checking if correct arguments are supplied for argtypeless
954 calls?
955
956 =item * Special library defaults for Strawberry Perl (requrest from
957 kthakore / SDL)
958
959 =item * Thread safety?
960
961 =item * Setup scripts (auto-generation of wrapper modules from headers)
962
963 =item * Raw data injection into functions (request from Shmuel Fomberg)
964
965 =over
966
967 =item * Type::Blob?
968
969 =back
970
971 =back
972
973 =head2 XS Cleanup
974
975 =over
976
977 =item * I<Check for void pointers after each Newxc>
978
979 =item * Finish Ctypes::valid_for_type function for other than int
980
981 =over
982
983 =item - This may be done?
984
985 =item - What about Pointers?
986
987 =item - What about UTF8?
988
989 =back
990
991 =back
992
993 =head2 Function / Library objects
994
995 =over
996
997 =item * Test/implement more complex "output arguments" functionality
998
999 =item * Cache function (in lib?) on CDLL->lib->func()
1000
1001 =item * Allow a sub as a restype (if func returns integer) in order
1002 to perform error checking.
1003
1004 =over
1005
1006 =item This is actually marked as deprecated, use errcheck attr now?
1007
1008 =back
1009
1010 =item * Python Ctypes requires everything but integers, strings and
1011 unicode strings "to be wrapped in their corresponding ctypes type,
1012 so that they can be converted to the required C data type".
1013
1014 Python Types:
1015
1016 =over
1017
1018 =item Sequence types: str, unicode, list, tuple, buffer, xrange
1019
1020 =item Numeric Types: int, float, long, complex
1021
1022 =item Dicts
1023
1024 =item Files
1025
1026 =item Iterators, generators, Sets, memoryview, contextmanager
1027
1028 =item Modules, Classes, Functions, Methods, Code, Type, Null,
1029 Boolean, Ellipsis
1030
1031 =back
1032
1033 We could maybe choose a sensible defaults?
1034
1035 =over
1036
1037 =item Numbers => depends on IOK/NOK
1038
1039 =item Strings => char* (check SvUTF8)
1040
1041 =item Arrays => lowest common denominator? (logic exists
1042 in Ctypes::Array)
1043
1044 =over
1045
1046 =item int, double, or char*
1047
1048 =item (logic exists in Ctypes::Array):
1049
1050 1) discern LCD
1051
1052 2) pack() appropriately
1053
1054 3) pass packed data
1055
1056 4) unpack() & modify original array
1057
1058 =back
1059
1060 =item Hashes => Build a Ctypes::Struct?
1061
1062 =back
1063
1064 An alternative would be to merge the two logics: if there are
1065 argtypes, accept anything and coerce. If there aren't argtypes,
1066 require ctypes obj wrapping.
1067
1068 =back
1069
1070 =head2 Callbacks
1071
1072 =over
1073
1074 =item * Make signature style more like Function's
1075
1076 =item * Update POD
1077
1078 =item * accessor methods
1079
1080 =back
1081
1082 =head2 Type objects
1083
1084 =over
1085
1086 =item * Casting
1087
1088 Should use same backend func as Ctypes::cast. Current implementation
1089 is ok, needs filled it out.
1090
1091 Cast will return a COPY of the casted object.
1092
1093 Python Ctypes does implicit casting of variables returned from foreign
1094 function calls:
1095
1096     "Fundamental data types, when returned as foreign function call
1097     results, or, for example, by retrieving structure field members
1098     or array items, are transparently converted to native Python
1099     types. In other words, if a foreign function has a restype of
1100     c_char_p, you will always receive a Python string, not a c_char_p
1101     instance.
1102
1103     "Subclasses of fundamental data types do not inherit this behavior.
1104     So, if a foreign functions restype is a subclass of c_void_p, you
1105     will receive an instance of this subclass from the function call.
1106     Of course, you can get the value of the pointer by accessing the
1107     value attribute."
1108
1109 =back
1110
1111 =head2 Arrays
1112
1113 =over
1114
1115 =item * Second (Python-style) API:
1116
1117     TenPointsArrayType = POINT * 10;    # POINT is a class
1118     arr = TenPointsArrayType();         # Step 2, get actual array!
1119
1120 =back
1121
1122 =head2 Pointers
1123
1124 Python Ctypes may converts pointers-to-type to the type itself in
1125 _build_callargs; see Python's _ctypes.c 3136-3156
1126
1127 =head2 Structs / Unions
1128
1129 =over
1130
1131 =item * Bit fields
1132
1133 =item * Change endianness on-demand
1134
1135 =back
1136
1137 =head2 Constants
1138
1139 Thin wrapper around ExtUtils::Constant?
1140
1141 =head2 Windows Conveniences
1142
1143 =over
1144
1145 =item COM objects?
1146
1147 =item Structured Exception Handling?
1148
1149 =item OLEDLL?
1150
1151 =item Defaulting to returning HRESULT
1152
1153 =item Auto-raise WindowsError on failure
1154
1155 =back
1156
1157 =head2 Header inspection
1158
1159 =over
1160
1161 =item L<GCC::TranslationUnit|GCC::TranslationUnit>?
1162
1163 =item External C parser like C::B::C?
1164
1165 =item Setup scripts (auto-generation of wrapper modules from
1166 headers)
1167
1168 =back
1169
1170 =head2 Full list of Simple data types to be implemented
1171
1172 =over
1173
1174 =item * Ctypes::c_int8
1175
1176     - ffi_type_sint8
1177     - pack c
1178     Represents the C 8-bit signed int datatype.
1179     Usually an alias for c_byte.
1180
1181 =item * Ctypes::c_uint8
1182
1183     - ffi_type_uint8
1184     - pack C
1185     Represents the C 8-bit unsigned int datatype.
1186     Usually an alias for c_ubyte.
1187
1188 =item * Ctypes::c_int16
1189
1190     - ffi_type_sint16
1191     Represents the C 16-bit signed int datatype.
1192     Usually an alias for c_short.
1193
1194 =item * Ctypes:c_uint16
1195
1196     - ffi_type_uint16
1197     Represents the C 16-bit unsigned int datatype.
1198     Usually an alias for c_ushort.
1199
1200 =item * Ctypes::c_int32
1201
1202     Represents the C 32-bit signed int datatype.
1203     Usually an alias for c_int.
1204
1205 =item * Ctypes::c_uint32
1206
1207     Represents the C 32-bit unsigned int datatype.
1208     Usually an alias for c_uint.
1209
1210 =item * Ctypes::c_int64
1211
1212     Represents the C 64-bit signed int datatype.
1213     Usually an alias for c_longlong.
1214
1215 =item * Ctypes::c_uint64
1216
1217     Represents the C 64-bit unsigned int datatype.
1218    Usually an alias for c_ulonglong.
1219
1220 =item * Ctypes::c_float
1221
1222     - ffi_type_float
1223     - f
1224     Represents the C double datatype.
1225     The constructor accepts an optional numeric initializer.
1226
1227 =item * Ctypes::c_double
1228
1229     - ffi_type_double
1230     - d
1231     Represents the C double datatype.
1232     The constructor accepts an optional numeric initializer.
1233
1234 =item * Ctypes::c_byte
1235
1236      - ffi_type_uint8
1237      - C
1238     Represents the C signed char datatype, and interprets the value as small integer.
1239     The constructor accepts an optional integer initializer
1240     Overflow checking Is done.
1241     Also accepts character initializer - **what does this mean for unicode?
1242
1243 =item * Ctypes::c_char
1244
1245     - ffi_type_uchar / ffi_type_schar (inspect $Config{'stdchar'})
1246     - C or c (inspect $Config{'stdchar'}, $Config{'charbits'}, $Config{'charsize'}
1247     Represents the C char datatype, and interprets the value as a single character.
1248     The constructor accepts an optional string initializer, the length of the string must be exactly one character.
1249
1250 =item * Ctypes::c_char_p
1251
1252     Represents the C char * datatype, which must be a pointer to a zero-terminated string.
1253     The constructor accepts an integer address, or a string.
1254     **what are addresses? How should they be expressed in Perl-land?
1255
1256 =item * Ctypes::c_ushort
1257
1258     Represents the C unsigned short datatype.
1259     The constructor accepts an optional integer initializer
1260     (No) overflow checking is done.
1261
1262 =item * Ctypes::c_short
1263
1264     Represents the C signed short datatype.
1265     The constructor accepts an optional integer initializer.
1266     (No) overflow checking is done.
1267
1268 =item * Ctypes::c_int
1269
1270     - ffi_type_sint
1271     Represents the C signed int datatype.
1272     The constructor accepts an optional integer initializer.
1273     (No) overflow checking is done.
1274     On platforms where sizeof(int) == sizeof(long) it is an alias to c_long.
1275
1276 =item * Ctypes::c_uint
1277
1278     Represents the C unsigned int datatype.
1279     The constructor accepts an optional integer initializer
1280     (No) overflow checking is done.
1281     On platforms where sizeof(int) == sizeof(long) it is an alias for c_ulong.
1282
1283 =item * Ctypes::c_ulong
1284
1285     Represents the C unsigned long datatype.
1286     The constructor accepts an optional integer initializer.
1287     (No) overflow checking is done.
1288
1289 =item * Ctypes::c_long
1290
1291     Represents the C signed long datatype.
1292     The constructor accepts an optional integer initializer
1293     (No) overflow checking is done.
1294
1295 =item * Ctypes::c_longlong
1296
1297     Represents the C signed long long datatype.
1298     The constructor accepts an optional integer initializer
1299     (No) overflow checking is done.
1300
1301 =item * Ctypes::c_size_t
1302
1303     Represents the C size_t datatype.
1304
1305 =item * Ctypes::c_ubyte
1306
1307     Represents the C unsigned char datatype, it interprets the value as small integer.
1308     The constructor accepts an optional integer initializer.
1309     (No) overflow checking is done.
1310
1311 =item * Ctypes::c_ulonglong
1312
1313     Represents the C unsigned long long datatype.
1314     The constructor accepts an optional integer initializer.
1315     (No) overflow checking is done.
1316
1317 =item * Ctypes::c_void_p
1318
1319     Represents the C void * type.
1320     The value is represented as integer.
1321     The constructor accepts an optional integer initializer.
1322
1323 =item * Ctypes::c_wchar
1324
1325     Represents the C wchar_t datatype
1326     Interprets the value as a single character unicode string.
1327     The constructor accepts an optional string initializer.
1328     The length of the string must be exactly one character.
1329
1330 =item * Ctypes::c_wchar_p
1331
1332     Represents the C wchar_t * datatype, which must be a pointer to a zero-terminated wide character string.
1333     The constructor accepts an integer address, or a string.
1334
1335 =back
1336
1337 =head1 AUTHOR
1338
1339 Ryan Jendoubi C<< <ryan.jendoubi at gmail.com> >>
1340
1341 Reini Urban C<< <rurban at x-ray.at> >>
1342
1343 =head1 BUGS
1344
1345 Please report any bugs or feature requests to C<bug-ctypes at
1346 rt.cpan.org>, or through the web interface at
1347 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Ctypes>.  I will be
1348 notified, and then you'll automatically be notified of progress on
1349 your bug as I make changes.
1350
1351 =head1 SUPPORT
1352
1353 You can see the proposed API and keep up to date with development at
1354 L<http://blogs.perl.org/users/doubi> or by following <at>doubious
1355 on Twitter or <at>doubi on Identi.ca.
1356
1357 You can find documentation for this module with the perldoc command.
1358
1359     perldoc Ctypes
1360
1361 You can also look for information at:
1362
1363 =over 4
1364
1365 =item * RT: CPAN's request tracker
1366
1367 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Ctypes>
1368
1369 =item * AnnoCPAN: Annotated CPAN documentation
1370
1371 L<http://annocpan.org/dist/Ctypes>
1372
1373 =item * CPAN Ratings
1374
1375 L<http://cpanratings.perl.org/d/Ctypes>
1376
1377 =item * Search CPAN
1378
1379 L<http://search.cpan.org/dist/Ctypes/>
1380
1381 =back
1382
1383 =head1 SEE ALSO
1384
1385 The 4 other Perl ffi libraries: L<Win32::API>, L<C::DynaLib>,
1386 L<FFI> and L<P5NCI>.
1387
1388 The Python, Ruby, Javascript and Pure integrations with
1389 L<libffi|http://sourceware.org/libffi/>.
1390
1391 You'll need the headers and/or description of the foreign
1392 library.
1393
1394 =head1 ACKNOWLEDGEMENTS
1395
1396 This module was created under the auspices of Google through their
1397 Summer of Code 2010. My deep thanks to Jonathan Leto, Reini Urban
1398 and Shlomi Fish for giving me the opportunity to work on the project.
1399
1400 =head1 LICENSE AND COPYRIGHT
1401
1402 Copyright 2010—2012 Ryan Jendoubi.
1403
1404 This program is free software; you can redistribute it and/or modify it
1405 under the terms of the Artistic License 2.0.
1406
1407 See http://dev.perl.org/licenses/ for more information.
1408
1409 =cut
1410
1411 1;
1412 __END__