exiftool-vendored.exe 12.82.0 → 12.84.0

package/bin/exiftool_files/lib/Win32/API.pm

@@ -641,834 +641,5 @@ __END__
 # DOCUMENTATION
 #
 
-=head1 NAME
-
-Win32::API - Perl Win32 API Import Facility
-
-=head1 SYNOPSIS
-
-  #### Method 1: with prototype
-
-  use Win32::API;
-  $function = Win32::API::More->new(
-      'mydll', 'int sum_integers(int a, int b)'
-  );
-  #### $^E is non-Cygwin only
-  die "Error: $^E" if ! $function;
-  #### or on Cygwin and non-Cygwin
-  die "Error: ".(Win32::FormatMessage(Win32::GetLastError())) if ! $function;
-  ####
-  $return = $function->Call(3, 2);
-
-  #### Method 2: with prototype and your function pointer
-
-  use Win32::API;
-  $function = Win32::API::More->new(
-      undef, 38123456, 'int name_ignored(int a, int b)'
-  );
-  die "Error: $^E" if ! $function; #$^E is non-Cygwin only
-  $return = $function->Call(3, 2);
-
-  #### Method 3: with parameter list 
-  
-  use Win32::API;
-  $function = Win32::API::More->new(
-      'mydll', 'sum_integers', 'II', 'I'
-  );
-  die "Error: $^E" if ! $function; #$^E is non-Cygwin only
-  $return = $function->Call(3, 2);
-     
-  #### Method 4: with parameter list and your function pointer
-  
-  use Win32::API;
-  $function = Win32::API::More->new(
-      undef, 38123456, 'name_ignored', 'II', 'I'
-  );
-  die "Error: $^E" if ! $function; #$^E is non-Cygwin only
-  $return = $function->Call(3, 2);
-  
-  #### Method 5: with Import (slightly faster than ->Call)
- 
-  use Win32::API;
-  $function = Win32::API::More->Import(
-      'mydll', 'int sum_integers(int a, int b)'
-  );
-  die "Error: $^E" if ! $function; #$^E is non-Cygwin only
-  $return = sum_integers(3, 2);
-
-
-=for LATER-UNIMPLEMENTED
-  #### or
-  use Win32::API mydll => 'int sum_integers(int a, int b)';
-  $return = sum_integers(3, 2);
-
-
-=head1 ABSTRACT
-
-With this module you can import and call arbitrary functions
-from Win32's Dynamic Link Libraries (DLL) or arbitrary functions for
-which you have a pointer (MS COM, etc), without having
-to write an XS extension. Note, however, that this module 
-can't do everything. In fact, parameters input and output is
-limited to simpler cases.
-
-A regular B<XS> extension is always safer and faster anyway.
-
-The current version of Win32::API is always available at your
-nearest CPAN mirror:
-
-  http://search.cpan.org/dist/Win32-API/
-
-A short example of how you can use this module (it just gets the PID of 
-the current process, eg. same as Perl's internal C<$$>):
-
-    use Win32::API;
-    Win32::API::More->Import("kernel32", "int GetCurrentProcessId()");
-    $PID = GetCurrentProcessId();
-
-Starting with 0.69. Win32::API initiated objects are deprecated due to numerous
-bugs and improvements, use Win32::API::More now. The use statement remains
-as C<use Win32::API;>.
-
-The possibilities are nearly infinite (but not all are good :-).
-Enjoy it.
-
-=head1 DESCRIPTION
-
-To use this module put the following line at the beginning of your script:
-
-    use Win32::API;
-
-You can now use the C<new()> function of the Win32::API module to create a
-new Win32::API::More object (see L<IMPORTING A FUNCTION>) and then invoke the 
-C<Call()> method on this object to perform a call to the imported API
-(see L<CALLING AN IMPORTED FUNCTION>).
-
-Starting from version 0.40, you can also avoid creating a Win32::API::More object
-and instead automatically define a Perl sub with the same name of the API
-function you're importing. This 2nd way using C<Import> to create a sub instead
-of an object is slightly faster than doing C<-E<gt>Call()>. The details of the
-API definitions are the same, just the method name is different:
-
-    my $GetCurrentProcessId = Win32::API::More->new(
-        "kernel32", "int GetCurrentProcessId()"
-    );
-    die "Failed to import GetCurrentProcessId" if !$GetCurrentProcessId;
-    $GetCurrentProcessId->UseMI64(1);
-    my $PID = $GetCurrentProcessId->Call();
-
-    #### vs.
-
-    my $UnusedGCPI = Win32::API::More->Import("kernel32", "int GetCurrentProcessId()");
-    die "Failed to import GetCurrentProcessId" if !$UnusedGCPI;
-    $UnusedGCPI->UseMI64(1);
-    $PID = GetCurrentProcessId();
-
-Note that C<Import> returns the Win32::API obj on success and false on failure
-(in which case you can check the content of C<$^E>). This allows some settings
-to be set through method calls that can't be specified as a parameter to Import,
-yet still have the convience of not writing C<-E<gt>Call()>. The Win32::API obj
-does not need to be assigned to a scalar. C<unless(Win32::API::More-E<gt>Import>
-is fine. Prior to v0.76_02, C<Import> returned returned 1 on success and 0 on
-failure.
-
-=head2 IMPORTING A FUNCTION
-
-You can import a function from a 32 bit Dynamic Link Library (DLL) file with
-the C<new()> function or, starting in 0.69, supply your own function pointer.
-This will create a Perl object that contains the reference to that function,
-which you can later C<Call()>.
-
-What you need to know is the prototype of the function you're going to import
-(eg. the definition of the function expressed in C syntax).
-
-Starting from version 0.40, there are 2 different approaches for this step:
-(the preferred) one uses the prototype directly, while the other (now deprecated)
-one uses Win32::API's internal representation for parameters.
-
-=head2 IMPORTING A FUNCTION BY PROTOTYPE
-
-You need to pass 2 or 3 parameters:
-
-=over 4
-
-=item 1.
-
-The name of the library from which you want to import the function. If the
-name is undef, you are requesting a object created from a function pointer,
-and must supply item 2.
-
-=item 2.
-
-This parameter is optional, most people should skip it, skip does not mean
-supplying undef. Supply a function pointer in the format of number 1234, not
-string "\x01\x02\x03\x04". Undef will be returned if the pointer is not
-readable, L<Win32::GetLastError|Win32/Win32::GetLastError()>/L<perlvar/"$^E">
-will be C<ERROR_NOACCESS>.
-
-=item 3.
-
-The C prototype of the function. If you are using a function pointer, the name
-of the function should be something "friendly" to you and no attempt is made
-to retrieve such a name from any DLL's export table. This name for a function
-pointer is also used for Import().
-
-=back
-
-When calling a function imported with a prototype, if you pass an
-undefined Perl scalar to one of its arguments, it will be
-automatically turned into a C C<NULL> value.
-
-See L<Win32::API::Type> for a list of the known parameter types and
-L<Win32::API::Struct> for information on how to define a structure.
-
-If a prototype type is exactly C<signed char> or C<unsigned char> for an 
-"in" parameter or the return parameter, and for "in" parameters only
-C<signed char *> or C<unsigned char *> the parameters will be treated as a
-number, C<0x01>, not C<"\x01">. "UCHAR" is not "unsigned char". Change the
-C prototype if you want numeric handling for your chars.
-
-=head2 IMPORTING A FUNCTION WITH A PARAMETER LIST
-
-You need to pass at minimum 4 parameters.
-
-=over 4
-
-=item 1.
-The name of the library from which you want to import the function.
-
-=item 2.
-This parameter is optional, most people should skip it, skip does not mean
-supplying undef. Supply a function pointer in the format of number C<1234>,
-not string C<"\x01\x02\x03\x04">. Undef will be returned if the pointer is not
-readable, L<Win32::GetLastError|Win32/Win32::GetLastError()>/L<perlvar/"$^E">
-will be C<ERROR_NOACCESS>.
-
-=item 3.
-The name of the function (as exported by the library) or for function pointers
-a name that is "friendly" to you. This name for a function pointer is also used
-for Import(). No attempt is made to retrieve such a name from any DLL's export
-table in the 2nd case.
-
-=item 4.
-The number and types of the arguments the function expects as input.
-
-=item 5.
-The type of the value returned by the function.
-
-=item 6.
-And optionally you can specify the calling convention, this defaults to
-'__stdcall', alternatively you can specify '_cdecl' or '__cdecl' (API > v0.68)
-or (API > v0.70_02) 'WINAPI', 'NTAPI', 'CALLBACK' (__stdcall), 'WINAPIV' (__cdecl) .
-False is __stdcall. Vararg functions are always cdecl. MS DLLs are typically
-stdcall. Non-MS DLLs are typically cdecl. If API > v0.75, mixing up the calling
-convention on 32 bits is detected and Perl will C<croak> an error message and
-C<die>.
-
-=back
-
-To better explain their meaning, let's suppose that we
-want to import and call the Win32 API C<GetTempPath()>.
-This function is defined in C as:
-
-    DWORD WINAPI GetTempPathA( DWORD nBufferLength, LPSTR lpBuffer );
-
-This is documented in the B<Win32 SDK Reference>; you can look
-for it on the Microsoft's WWW site, or in your C compiler's 
-documentation, if you own one.
-
-=over 4
-
-=item B<1.>
-
-The first parameter is the name of the library file that 
-exports this function; our function resides in the F<KERNEL32.DLL>
-system file.
-
-When specifying this name as parameter, the F<.DLL> extension
-is implicit, and if no path is given, the file is searched through
-a couple of directories, including: 
-
-=over 4
-
-=item 1. The directory from which the application loaded. 
-
-=item 2. The current directory. 
-
-=item 3. The Windows system directory (eg. c:\windows\system or system32).
-
-=item 4. The Windows directory (eg. c:\windows).
-
-=item 5. The directories that are listed in the PATH environment variable. 
-
-=back
-
-You may, but don't have to write F<C:\windows\system\kernel32.dll>; or
-F<kernel32.dll>, only F<kernel32> is enough:
-
-    $GetTempPath = new Win32::API::More('kernel32', ...
-
-=item B<2.>
-
-Since this function is from a DLL, skip the 2nd parameter. Skip does not
-mean supplying undef.
-
-=item B<3.>
-
-Now for the real second parameter: the name of the function.
-It must be written exactly as it is exported 
-by the library (case is significant here).
-If you are using Windows 95 or NT 4.0, you can use the B<Quick View> 
-command on the DLL file to see the function it exports. 
-Remember that you can only import functions from 32 or 64 bit DLLs:
-in Quick View, the file's characteristics should report
-somewhere "32 bit word machine"; as a rule of thumb,
-when you see that all the exported functions are in upper case,
-the DLL is a 16 bit one and you can't use it. You also can not load a 32 bit
-DLL into a 64 bit Perl, or vice versa. If you try, C<new>/C<Import> will fail
-and C<$^E> will be C<ERROR_BAD_EXE_FORMAT>.
-If their capitalization looks correct, then it's probably a 32 bit
-DLL. If you have Platform SDK or Visual Studio, you can use the Dumpbin
-tool. Call it as C<dumpbin /exports name_of_dll.dll> on the command line.
-If you have Mingw GCC, use objdump as
-C<objdump -x name_of_dll.dll E<gt> dlldump.txt> and search for the word exports
-in the very long output.
-
-Also note that many Win32 APIs are exported twice, with the addition of
-a final B<A> or B<W> to their name, for - respectively - the ASCII 
-and the Unicode version.
-When a function name is not found, Win32::API will actually append
-an B<A> to the name and try again; if the extension is built on a
-Unicode system, then it will try with the B<W> instead.
-So our function name will be:
-
-    $GetTempPath = new Win32::API::More('kernel32', 'GetTempPath', ...
-
-In our case C<GetTempPath> is really loaded as C<GetTempPathA>.
-
-=item B<4.>
-
-The third parameter, the input parameter list, specifies how many 
-arguments the function wants, and their types. It can be passed as
-a single string, in which each character represents one parameter, 
-or as a list reference. The following forms are valid:
-
-    "abcd"
-    [a, b, c, d]
-    \@LIST
-
-But those are not:
-
-    (a, b, c, d)
-    @LIST
-
-The number of characters, or elements in the list, specifies the number 
-of parameters, and each character or element specifies the type of an 
-argument; allowed types are:
-
-=over 4
-
-=item C<I>: 
-value is an unsigned integer (unsigned int)
-
-=item C<i>: 
-value is an signed integer (signed int or int)
-
-=item C<N>: 
-value is a unsigned pointer sized number (unsigned long)
-
-=item C<n>: 
-value is a signed pointer sized number (signed long or long)
-
-=item C<Q>: 
-value is a unsigned 64 bit integer number (unsigned long long, unsigned __int64)
-See next item for details.
-
-=item C<q>:
-value is a signed 64 bit integer number (long long, __int64)
-If your perl has 'Q'/'q' quads support for L<perlfunc/pack> then Win32::API's 'q'
-is a normal perl numeric scalar. All 64 bit Perls have quad support. Almost no
-32 bit Perls have quad support. On 32 bit Perls, without quad support,
-Win32::API's 'q'/'Q' letter is a packed 8 byte string. So C<0x8000000050000000>
-from a perl with native Quad support would be written as
-C<"\x00\x00\x00\x50\x00\x00\x00\x80"> on a 32 bit Perl without Quad support.
-To improve the use of 64 bit integers with Win32::API on a 32 bit Perl without
-Quad support, there is a per Win32::API::* object setting called L</UseMI64>
-that causes all quads to be accepted as, and returned as L<Math::Int64> objects.
-For "in" params in Win32::API and Win32::API::More and "out" in
-Win32::API::Callback only, if the argument is a reference, it will automatically
-be treated as a Math::Int64 object without having to previously call
-L</UseMI64>.
-
-=item C<F>: 
-value is a single precision (4 bytes) floating point number (float)
-
-=item C<D>: 
-value is a double precision (8 bytes) floating point number (double)
-
-=item C<S>: 
-value is a unsigned short (unsigned short)
-
-=item C<s>: 
-value is a signed short (signed short or short)
-
-=item C<C>: 
-value is a char (char), pass as C<"a">, not C<97>, C<"abc"> will truncate to C<"a">
-
-=item C<P>: 
-value is a pointer (to a string, structure, etc...)
-padding out the buffer string is required, buffer overflow detection is
-performed. Pack and unpack the data yourself. If P is a return type, only
-null terminated strings or NULL pointer are supported. If P is an in type, NULL
-is integer C<0>. C<undef>, C<"0">, and C<""+0> are not integer C<0>, C<"0"+0> is
-integer C<0>.
-
-It is suggested to
-not use P as a return type and instead use N and read the memory yourself, and
-free the pointer if applicable. This pointer is effectively undefined after the
-C function returns control to Perl. The C function may not hold onto it after
-the C function returns control. There are exceptions where the pointer will
-remain valid after the C function returns control, but tread at your own risk,
-and at your knowledge of Perl interpreter's C internals.
-
-=item C<T>: 
-value is a Win32::API::Struct object, in parameter only, pass by reference
-(pointer) only, pass by copy not implemented, see other sections for more
-
-=item C<K>:
-value is a Win32::API::Callback object, in parameter only, (see L<Win32::API::Callback>)
-
-=item C<V>:
-no value, no parameters, stands for C<void>, may not be combined with any other
-letters, equivalent to a ""
-
-=back
-
-For beginners, just skip this paragraph.
-Note, all parameter types are little endian. This is probably what you want
-unless the documentation for the C function you are calling explicitly says
-the parameters must be big endian. If there is no documentation for your C
-function or no mention of endianess in the documentation, this doesn't apply
-to you and skip the rest of this paragraph. There is no inherent support
-for big endian parameters. Perl's scalar numbers model is that numeric
-scalars are effectively opaque and their machine representation is
-irrelevant. On Windows Perl, scalar numbers are little endian
-internally. So C<$number = 5; print "$number";> will put 5 on the screen.
-C<$number> given to Win32::API will pass little endian integer 5 to the C
-function call. This is almost surly what you want. If you really must pass
-a big endian integer, do C<$number = unpack('L', pack('N', 5));>, then
-C<print "$number";> will put 83886080 on the screen, but this is big endian 5,
-and passing 83886080 to C<-E<gt>Call()> will make sure that
-the C function is getting big endian 5. See L<perlpacktut> for more.
-
-Our function needs two parameters: a number (C<DWORD>) and a pointer to a 
-string (C<LPSTR>):
-
-    $GetTempPath = new Win32::API('kernel32', 'GetTempPath', 'NP', ...
-
-=item B<4.>
-
-The fourth is the type of the value returned by the 
-function. It can be one of the types seen above, plus another type named B<V> 
-(for C<void>), used for functions that do not return a value.
-In our example the value returned by GetTempPath() is a C<DWORD>, which is a
-typedef for unsigned long, so our return type will be B<N>:
-
-    $GetTempPath = new Win32::API::More('kernel32', 'GetTempPath', 'NP', 'N');
-
-Now the line is complete, and the GetTempPath() API is ready to be used
-in Perl. Before calling it, you should test that $GetTempPath is 
-L<perlfunc/defined>, otherwise errors such as the function or the library could
-not be loaded or the C prototype was unparsable happened, and no object was
-created. If the return value is undefined, to get detailed error status, use
-L<perlvar/"$^E"> or L<Win32::GetLastError|Win32/Win32::GetLastError()>. C<$^E>
-is slower than C<Win32::GetLastError> and useless on Cygwin, but C<$^E> in
-string context provides a readable description of the error. In numeric context,
-C<$^E> is equivelent to C<Win32::GetLastError>. C<Win32::GetLastError> always
-returns an integer error code. You may use
-L<Win32::FormatMessage|Win32/Win32::FormatMessage()> to convert an integer error
-code to a readable description on Cygwin and Native builds of Perl.
-
-Our definition, with error checking added, should then look like this:
-
-    $GetTempPath = new Win32::API::More('kernel32', 'GetTempPath', 'NP', 'N');
-    if(not defined $GetTempPath) {
-        die "Can't import API GetTempPath: $^E\n";
-    }
-
-=back
-
-=head2 CALLING AN IMPORTED FUNCTION
-
-To effectively make a call to an imported function you must use the
-Call() method on the Win32::API object you created.
-Continuing with the example from the previous paragraph, 
-the GetTempPath() API can be called using the method:
-
-    $GetTempPath->Call(...
-
-Of course, parameters have to be passed as defined in the import phase.
-In particular, if the number of parameters does not match (in the example,
-if GetTempPath() is called with more or less than two parameters), 
-Perl will C<croak> an error message and C<die>.
-
-The two parameters needed here are the length of the buffer
-that will hold the returned temporary path, and a pointer to the 
-buffer itself.
-For numerical parameters except for char, you can use either a constant expression
-or a variable, it will be numified similar to the expression C<($var+0)>.
-For pointers, also note that B<memory must be allocated before calling the function>,
-just like in C.
-For example, to pass a buffer of 80 characters to GetTempPath(),
-it must be initialized before with:
-
-    $lpBuffer = " " x 80;
-
-This allocates a string of 80 characters. If you don't do so, you'll
-probably get a fatal buffer overflow error starting in 0.69.
-The call should therefore include:
-
-    $lpBuffer = " " x 80;
-    $GetTempPath->Call(80, $lpBuffer);
-
-And the result will be stored in the $lpBuffer variable.
-Note that you never need to pass a reference to the variable
-(eg. you B<don't need> C<\$lpBuffer>), even if its value will be set 
-by the function. 
-
-A little problem here is that Perl does not trim the variable, 
-so $lpBuffer will still contain 80 characters in return; the exceeding 
-characters will be spaces, because we said C<" " x 80>.
-
-In this case we're lucky enough, because the value returned by 
-the GetTempPath() function is the length of the string, so to get
-the actual temporary path we can write:
-
-    $lpBuffer = " " x 80;
-    $return = $GetTempPath->Call(80, $lpBuffer);
-    $TempPath = substr($lpBuffer, 0, $return);
-
-If you don't know the length of the string, you can usually
-cut it at the C<\0> (ASCII zero) character, which is the string
-delimiter in C:
-
-    $TempPath = ((split(/\0/, $lpBuffer))[0];  
-    # or    
-    $lpBuffer =~ s/\0.*$//;
-
-=head2 USING STRUCTURES
-
-Starting from version 0.40, Win32::API comes with a support package
-named Win32::API::Struct. The package is loaded automatically with
-Win32::API, so you don't need to use it explicitly.
-
-With this module you can conveniently define structures and use
-them as parameters to Win32::API functions. A short example follows:
-
-
-    # the 'POINT' structure is defined in C as:
-    #     typedef struct {
-    #        LONG  x;
-    #        LONG  y;
-    #     } POINT;
-    
-
-    #### define the structure
-    Win32::API::Struct->typedef( POINT => qw{
-        LONG x; 
-        LONG y; 
-    });
-    
-    #### import an API that uses this structure
-    Win32::API->Import('user32', 'BOOL GetCursorPos(LPPOINT lpPoint)');
-    
-    #### create a 'POINT' object
-    my $pt = Win32::API::Struct->new('POINT');
-    
-    #### call the function passing our structure object
-    GetCursorPos($pt);
-    
-    #### and now, access its members
-    print "The cursor is at: $pt->{x}, $pt->{y}\n";
-
-Note that this works only when the function wants a 
-B<pointer to a structure>, not a "pass by copy" structure. As you can see, our
-structure is named 'POINT', but the API used 'LPPOINT'. Some heuristics are
-done to validate the argument's type vs the parameter's type if the function
-has a C prototype definition (not letter definition). First, if the parameter
-type starts with the LP prefix, the LP prefix is stripped, then compared to
-the argument's type. If that fails, the Win32::API::Type database
-(see L<Win32::API::Type/typedef>)
-will be used to convert the parameter type to the base type. If that fails,
-the parameter type will be stripped of a trailing whitespace then a '*', and
-then checked against the base type. L<Dies|perlfunc/die> if the parameter and
-argument types do not match after 3 attempts.
-
-For more information, see also L<Win32::API::Struct>.
-
-If you don't want (or can't) use the C<Win32::API::Struct> facility,
-you can still use the low-level approach to use structures:
-
-=over 4
-
-=item 1.
-
-you have to L<pack()|perlfunc/pack> the required elements in a variable:
-
-    $lpPoint = pack('ll', 0, 0); # store two LONGs
-
-=item 2.
-
-to access the values stored in a structure, L<unpack()|perlfunc/unpack> it as required:
-
-    ($x, $y) = unpack(';;', $lpPoint); # get the actual values
-
-=back
-
-The rest is left as an exercise to the reader...
-
-=head2 EXPORTED FUNCTIONS
-
-=head3 ReadMemory
-
-    $copy_of_memblock = ReadMemory($SourcePtr, $length);
-
-Reads the source pointer for C<$length> number of bytes. Returns a copy of
-the memory block in a scalar. No readability checking is done on C<$SourcePtr>.
-C<$SourcePtr>'s format is 123456, not C<"\x01\x02\x03\x04">.
-
-=head3 WriteMemory
-
-    WriteMemory($DestPtr, $sourceScalar, $length);
-
-Copies the string contents of the C<$sourceScalar> scalar to C<$DestPtr> for
-C<$length> bytes. $length must be less than or equal to the length of
-C<$sourceScalar>, otherwise the function croaks. No readability checking is
-done on C<$DestPtr>. C<$DestPtr>'s format is 123456, not
-C<"\x01\x02\x03\x04">. Returns nothing.
-
-=head3 MoveMemory
-
-    MoveMemory($destPtr, $sourcePtr, $length);
-
-Copies a block of memory from one location to another. The source and
-destination blocks may overlap. All pointers are in the format of 123456,
-not C<"\x01\x02\x03\x04">.  No readability checking is done. Returns nothing.
-
-=head3 IsBadReadPtr
-
-    if(IsBadReadPtr($ptr, $length)) {die "bad ptr";}
-
-Probes a memory block for C<$length> bytes for readability. Returns true if
-access violation occurs, otherwise false is returned. This function is useful
-to avoid dereferencing pointers which will crash the perl process. This function
-has many limitations, including not detecting uninitialized memory, not
-detecting freed memory, and not detecting gibberish. It can not tell whether a
-function pointer is valid x86 machine code. Ideally, you should never use it,
-or remove it once your code is stable. C<$ptr> is in the format of 123456,
-not C<"\x01\x02\x03\x04">. See MS's documentation for a lot more
-on this function of the same name.
-
-=head3 SafeReadWideCString
-
-    $source = Encode::encode("UTF-16LE","Just another perl h\x{00E2}cker\x00");
-    $string = SafeReadWideCString(unpack('J',pack('p', $source)));
-    die "impossible" if $source ne "Just another perl h\x{00E2}cker";
-
-Safely (SEH aware) reads a utf-16 wide null terminated string (the first and
-only parameter), into a scalar. Returns undef, if an access violation happens
-or null pointer (same thing). The string pointer is in the format of 123456,
-not C<"\x01\x02\x03\x04">. The returned scalar will be UTF8 marked if the string
-can not be represented in the system's ANSI codepage. Conversion is done with
-WideCharToMultiByte. Returns a 0 length scalar string if WideCharToMultiByte fails.
-This function was created because L<pack's|perlfunc/pack> p letter won't read UTF16
-and L</ReadMemory> and L</IsBadReadPtr> require an explicit length.
-
-=head2 CONSTRUCTORS
-
-=head3 new
-
-    $obj = Win32::API::More->new([$dllname | (undef , $funcptr)], [$c_proto | ($in, $out [, $calling_convention])]);
-
-See L</DESCRIPTION>.
-
-=head3 Import
-    $obj = Win32::API::More->Import([$dllname | (undef , $funcptr)], [$c_proto | ($in, $out [, $calling_convention])]);
-
-See L</DESCRIPTION>.
-
-=head2 METHODS
-
-=head3 Call
-
-The main method of a Win32::API object. Documented elsewhere in this document.
-
-=head3 UseMI64
-
-    $bool = $APIObj->UseMI64();
-    $oldbool = $APIObj->UseMI64($newbool);
-
-Turns on Quads as L<Math::Int64> objects support for a particular object
-instance. You must call L<perlfunc/use>/L<perlfunc/require> on Math::Int64
-before calling UseMI64. Win32::API does not C<use> Math::Int64 for you.
-Works on Win32::API and Win32::API::Callback objects. This method
-does not exist if your Perl natively supports Quads (64 bit Perl for example).
-Takes 1 optional parameter, which is a true or false value to use or don't use
-Math::Int64, returns the old setting, which is a true or false value. If called
-without any parameters, returns current setting, which is a true or false value,
-without setting the option. As discussed in L</q>, if you are not using
-Math::Int64 you must supply/will receive 8 byte scalar strings for quads.
-For "in" params in Win32::API and Win32::API::More and "out" in
-Win32::API::Callback only, if the argument is a reference, it will automatically
-be treated as a Math::Int64 object without having to previously call this
-function.
-
-=head2 VERBOSE DEBUGGING
-
-If using C<Win32::GetLastError> and C<$^E> does not reveal the problem with your
-use of Win32::API, you may turn on Win32::API's very verbose debugging mode as
-follows
-
-    BEGIN {
-        $Win32::API::DEBUG = 1;
-    }
-    use Win32::API;
-    $function = Win32::API::More->new(
-        'mydll', 'int sum_integers(int a, int b)'
-    );
-
-=head1 HISTORY
-
-=over 4
-
-=item UseMI64 API change
-
-Starting in 0.71, UseMI64 on a set returns old value, not previously
-new value.
-
-=item fork safe
-
-Starting in 0.71, a Win32::API object can go through a fork and work
-correctly in the child and parent psuedo-processes. Previously when either
-psuedo-processes exited, the DLL would be unloaded and the other
-psuedo-processes would crash if a Call() was done on the object.
-
-=item return value signedness
-
-Prior to 0.69, for numeric integer types, the return scalar was always signed.
-Unsigned-ness was ignored.
-
-=item shorts
-
-Prior to 0.69, shorts were not supported. 'S' meant a sturct. To fix this
-Win32::API::More class was created for 0.69. 'S'/'s' now means short, per pack's
-letters. Struct has been moved to letter 'T'. Win32::API will continue to exist
-for legacy code.
-
-=item float return types
-
-Prior to 0.69, if a function had a return type of float, it was silently
-not called.
-
-=item buffer overflow protection
-
-Introduced in 0.69. If disabling is required, which is highly
-B<not recommended>, set an environmental variable called
-WIN32_API_SORRY_I_WAS_AN_IDIOT to 1.
-
-=item automatic un/pack
-
-Starting with 0.69, when using Win32::API::More, there is automatic un/packing
-of pointers to numbers-ish things for in parameters when using the C
-prototype interface.
-
-=item Quads on 32 bit
-
-Added in 0.70.
-
-=item __stdcall vs __cdecl checking on 32 bits
-
-Added in 0.76_01
-
-=item Import returns an api obj on success, undef on failure, instead of 1 or 0
-
-Added in 0.76_02
-
-=item checking C<$!> for C<new>/C<Import> failure is broken and deprecated
-
-Starting in 0.76_06, due to many bugs with C<new> and C<Import> not setting
-L<perlvar/$!> or Win32 and C error codes overlapping and Win32 error codes being
-stringified as different C error codes, checking C<$!> is deprecated and the
-existing, partial setting of C<$!>, maybe removed in the future. Only check
-C<Win32::GetLastError()> or C<$^E> to find out why the call failed.
-
-=back
-
-See the C<Changes> file for more details, many of which not mentioned here.
-
-=head1 BUGS AND LIMITATIONS
-
-=over 4
-
-=item E<nbsp> Unicode DLL paths
-
-Untested.
-
-=item E<nbsp> ithreads
-
-Minimally tested.
-
-=item E<nbsp> C functions getting utf8 scalars vs byte scalars
-
-Untested and undefined.
-
-=back
-
-=head1 SEE ALSO
-
-L<Math::Int64>
-
-L<Win32::API::Struct>
-
-L<Win32::API::Type>
-
-L<Win32::API::Callback>
-
-L<Win32::API::Callback::IATPatch>
-
-L<http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/function-calling-conventions.html>
-
-=head1 AUTHOR
-
-Aldo Calpini ( I<dada@perl.it> ).
-
-=head1 MAINTAINER
-
-Cosimo Streppone ( I<cosimo@cpan.org> )
-
-=head1 MAJOR CONTRIBUTOR
-
-Daniel Dragan ( I<bulkdd@cpan.org> )
-
-=head1 LICENSE
-
-To finally clarify this, C<Win32::API> is OSI-approved free software;
-you can redistribute it and/or modify it under the same terms as Perl
-itself.
-
-See L<http://dev.perl.org/licenses/artistic.html>
-
-=head1 CREDITS
-
-All the credits go to Andrea Frosini for the neat assembler trick
-that makes this thing work. I've also used some work by Dave Roth
-for the prototyping stuff. A big thank you also to Gurusamy Sarathy
-for his invaluable help in XS development, and to all the Perl
-community for being what it is.
-
-Cosimo also wants to personally thank everyone that contributed
-to Win32::API with complaints, emails, patches, RT bug reports
-and so on.
-
-=cut
+#line 1474