Merge branch 'patch-1' of github.com:dsteinbrunner/perl5-win32-api

Conflicts:
	API.pm

Resolved conflicts from other edits done
by bulkdd on API.pm documentation.

Author: Cosimo Streppone

API.pm

@@ -607,8 +607,8 @@ sub parse_prototype {
 
 #
 # XXX hack, see the proper implementation in TODO
-# The point here is dont let fork children free the parent's DLLs.
-# CLONE runs on ::API and ::More, thats bad and causes a DLL leak, make sure
+# The point here is don't let fork children free the parent's DLLs.
+# CLONE runs on ::API and ::More, that's bad and causes a DLL leak, make sure
 # CLONE dups the DLL handles only once per CLONE
 # GetModuleHandleEx was not used since that is a WinXP and newer function, not Win2K.
 # GetModuleFileName was used to get full DLL pathname incase SxS/multiple DLLs
@@ -794,7 +794,7 @@ readable, GetLastError will be ERROR_NOACCESS.
 
 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 retrive such a name from any DLL's export table. This name for a function
+to retrieve such a name from any DLL's export table. This name for a function
 pointer is also used for Import().
 
 =back
@@ -830,7 +830,7 @@ readable, GetLastError will be 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 retrive such a name from any DLL's export
+for Import(). No attempt is made to retrieve such a name from any DLL's export
 table in the 2nd case.
 
 =item 4.
@@ -1006,11 +1006,11 @@ 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 effectivly undefined after the
+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 interpretor's C internals.
+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
@@ -1021,25 +1021,25 @@ value is a Win32::API::Callback object, in parameter only, (see L<Win32::API::Ca
 
 =item C<V>:
 no value, no parameters, stands for C<void>, may not be combined with any other
-letters, equivelent to a "" 
+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 explictly says
+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 doucmentation, this doesn't apply
-to you and skip the rest of this paragraph. There is no inherant support
+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 effectivly opaque and their machine representation is
-irrelavent. On Windows Perl, scalar numbers are little endian
+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 that
+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 
@@ -1166,8 +1166,8 @@ them as parameters to Win32::API functions. A short example follows:
 
 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 herustics are
-done to vaildate the argument's type vs the parameter's type if the function
+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
@@ -1236,10 +1236,10 @@ 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 giberrish. It can not tell whether a
+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 alot more
+not C<"\x01\x02\x03\x04">. See MS's documentation for a lot more
 on this function of the same name.
 
 =head3 SafeReadWideCString
@@ -1331,7 +1331,7 @@ not called.
 =item buffer overflow protection
 
 Introduced in 0.69. If disabling is required, which is highly
-B<not recommended>, set an enviromental variable called
+B<not recommended>, set an environmental variable called
 WIN32_API_SORRY_I_WAS_AN_IDIOT to 1.
 
 =item automatic un/pack
@@ -1413,7 +1413,7 @@ See L<http://dev.perl.org/licenses/artistic.html>
 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 unvaluable help in XS development, and to all the Perl
+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

Callback.pm

@@ -55,7 +55,7 @@ BEGIN {
     *PTRSIZE = *Win32::API::PTRSIZE;
     sub PTRLET ();
     *PTRLET = *Win32::API::Type::pointer_pack_type;
-    if(OPV <= 5.008000){ #dont have unpackstring in C
+    if(OPV <= 5.008000){ #don't have unpackstring in C
         eval('sub _CallUnpack {return unpack($_[0], $_[1]);}');
     }
 }
@@ -133,7 +133,7 @@ sub MakeStruct {
 #    for(@{$self->{intypes}}){ #elements of intypes are not 1 to 1 with stack params
 #        my ($typeletter, $packedparam, $finalParam, $unpackletter)  = ($_, $arr->[$i]);
 #        
-#        #structs dont work, this is broken code from old version
+#        #structs don't work, this is broken code from old version
 #        #$self->{intypes} is letters types not C prototype params
 #        #C prototype support would have to exist for MakeStruct to work
 #        if(    $typeletter eq 'S' || $typeletter eq 's'){
@@ -317,7 +317,7 @@ sub MakeCB{
     .("\x50"#           push    eax
     ."\xB8").$Stage2FuncPtrPkd # mov     eax, 0C0DE0001h
     .("\xFF\xD0"#       call    eax
-    #since ST(0) is volatile, we dont care if we fill it with garbage
+    #since ST(0) is volatile, we don't care if we fill it with garbage
     ."\x80\x7D\xFE\x00"#cmp    [ebp+FuncRtnCxtVar.F_Or_D], 0
     ."\x74\x05"#       jz      5 bytes
     ."\xDD\x45\xF4"#   fld     qword ptr [ebp+retval] (double)
@@ -326,7 +326,7 @@ sub MakeCB{
     #rewind sp to entry sp, no pop push after this point
     ."\x83\xC4\x24"#   add     esp, 24h
     ."\x8B\x45\xF4"#   mov     eax, dword ptr [ebp+retval]
-    #edx might be garbage, we dont care, caller only looks at volatile
+    #edx might be garbage, we don't care, caller only looks at volatile
     #registers that the caller's prototype says the caller does
     ."\x8B\x55\xF8"#   mov     edx, dword ptr [ebp+retval+4]
     #can't use retn op, it requires a immediate count, our count is in a register
@@ -339,7 +339,7 @@ sub MakeCB{
 
 
     #begin x64 part
-    #these packs dont constant fold in < 5.17 :-(
+    #these packs don't constant fold in < 5.17 :-(
     #they are here for readability
     :(''.pack('C', 0b01000000 #REX base
             | 0b00001000 #REX.W
@@ -509,7 +509,7 @@ that causes all quads to be accepted as, and returned as L<Math::Int64>
 objects. 4 to 8 byte long pass by copy/return type C aggregate types
 are very rare in Windows, but they are supported as "in" and return
 types by using 'q'/'Q' on 32 and 64 bits. Converting between the C aggregate
-and its representation as a quad is upto the reader. For "out" in
+and its representation as a quad is up to the reader. For "out" in
 Win32::API::Callback (not "in"), if the argument is a reference, it will
 automatically be treated as a Math::Int64 object without having to
 previously call this function.
@@ -523,7 +523,7 @@ value is a double precision number (double)
 =item C<Unimplemented types>:
 Unimplemented in Win32::API::Callback types such as shorts, chars, and
 smaller than "machine word size" (32/64bit) numbers can be processed
-by specifiying N, then masking off the high bytes.
+by specifying N, then masking off the high bytes.
 For example, to get a char, specify N, then do C<$numeric_char = $_[2] & 0xFF;>
 in your Perl callback sub. To get a short, specify N, then do
 C<$numeric_char = $_[2] & 0xFFFF;> in your Perl callback sub.
@@ -539,7 +539,7 @@ C<$numeric_char = $_[2] & 0xFFFF;> in your Perl callback sub.
     $CallbackObj = Win32::API::Callback->new( sub { print "hello world";},
                                             $in, $out);
 
-Creates and returns a new Win32::API::Callback object. Calling convetion
+Creates and returns a new Win32::API::Callback object. Calling convention
 parameter is optional.  Calling convention parameter has same behaviour as
 Win32::API's calling convention parameter. C prototype parsing of Win32::API
 is not available with Win32::API::Callback. If the C caller assumes the
@@ -548,7 +548,7 @@ parameters, if they are floats or doubles they will be garbage. Note there is
 no way to create a Win32::API::Callback callback with a vararg prototype.
 A workaround is to put "enough" Ns as the in types, and stop looking at the @_
 slices in your Perl sub callback after a certain count. Usually the first
-parameter will somehow indiciate how many additional stack parameters you are
+parameter will somehow indicate how many additional stack parameters you are
 receiving. The Ns in @_ will eventually become garbage, technically they are
 the return address, saved registers, and C stack allocated variables of the
 caller. They are effectivly garbage for your vararg callback. All vararg

IATPatch.pod

@@ -40,7 +40,7 @@ Win32::API::Callback::IATPatch - Hooking and Patching a DLL's Imported C Functio
 Win32::API::Callback::IATPatch allows you to hook a compile time dynamic linked
 function call from any DLL (or EXE, from now on all examples are from a DLL to
 another DLL, but from a EXE to a DLL is implied) in the Perl process, to a
-differnt DLL in the same Perl process, by placing a Win32::API::Callback object
+different DLL in the same Perl process, by placing a Win32::API::Callback object
 in between. This module does B<not> hook B<GetProcAddress> function calls. It
 also will not hook a function call from a DLL to another function in the same
 DLL. The function you want to hook B<must> appear in the B<import table> of the
@@ -62,13 +62,13 @@ script creates IATPatch object, where calls from that new DLL goto the real
 destination function without hooking. If a DLL is unloaded, then reloaded into
 the process, you must call C<Unpatch(0)> method on the old IATPatch object, then
 create a new IATPatch object. IATPatch has no notification feature that a DLL
-is being loaded or unloaded from the process. Unless you completly control, and
+is being loaded or unloaded from the process. Unless you completely control, and
 have the source code of the caller DLL, and understand all of the source code of
 that DLL, there is a high chance that you will B<NOT> hook all calls from that
-DLL to the destionation function. If a call to the destination function is
+DLL to the destination function. If a call to the destination function is
 dangerous or unacceptable, do not use IATPatch. IATPatch is not Microsoft
 Detours or the like in any sense. Detours and its brethern will rewrite the
-machine code in the begining of the destination function call, hooking all
+machine code in the beginning of the destination function call, hooking all
 calls to that function call process wide, without exception.
 
 Why this module was created? So I created create mock kernel32 functions to
@@ -82,7 +82,7 @@ unit test Perl's C function calls to Kernel32.
   $A_Win32_API_Callback_Obj,    $EXE_or_DLL_hmodule_or_name_to_hook,
   $import_DLL_name,             $import_function_name_or_ordinal);
 
-Creates a new IATPatch object. The Win32::API::Callback will be called aslong
+Creates a new IATPatch object. The Win32::API::Callback will be called as long
 as the IATPatch object exists. When an IATPatch object is DESTROYed, unless
 C<-E<gt>Unpatch(0)> is called first, the patch is undone and the original
 function is directly called from then on by that DLL. The DLL is not reference

Struct.pm

@@ -237,7 +237,7 @@ sub getPack {
     my @buffer_ptrs = (); #this contains the struct_ptrs that were placed in the
     #the struct, its part of "C func changes the struct ptr to a private allocated
     #struct" code, it is push/poped only for struct ptrs, it is NOT a 1 to
-    #1 mapping between all struct members, so dont access it with indexes
+    #1 mapping between all struct members, so don't access it with indexes
 
     my $align = $self->align();
 
@@ -411,7 +411,7 @@ else{ #new ptr is true
     }
 #must fix {buffer} with contents of the new struct, $structptr might be
 #null or might be a SVPV from a ::Struct that was ignored, in any case,
-#a forign memory allocator is at work here
+#a foreign memory allocator is at work here
     $$SVMemberRef->{buffer} = Win32::API::ReadMemory($newstructptr, $$SVMemberRef->sizeof)
         if($oldstructptr != $newstructptr);
 #always must be called, if new ptr is not null, at this point, C func, did
@@ -584,7 +584,7 @@ function takes care of removing the semicolon after the member
 name. Win32::API::Struct does B<NOT> support Enums, Unions, or Bitfields.
 C<NAME> must not end in C<*>, typedef creates structs, not struct pointers.
 See L<Win32::API::Type/"typedef">
-on howto create a struct pointer type. Returns true on success, and undef on error.
+on how to create a struct pointer type. Returns true on success, and undef on error.
 On error it L<warns|perlfunc/warn> with the specific reason.
 
 The synopsis example could be written like this:
@@ -600,7 +600,7 @@ syntax), which is pretty cool:
   };
 
 L<Win32::API/Call> automatically knows that an 'LPNAME' type, refers
-to a 'NAME' type struct. Also see L<Win32::API::Type/"typedef"> on howto declare
+to a 'NAME' type struct. Also see L<Win32::API::Type/"typedef"> on how to declare
 pointers to struct types.
 
 Unlike in Win32::API, a single non-array char or CHAR struct member in a
@@ -697,9 +697,9 @@ allocator. Some C APIs give you static global buffers which never are freed or f
 automatically in the next call to a function from to that DLL.
 
 With foreign allocators, its best to treat to write a pointer class, bless the
-ref to scalar interger (holding the pointer) into that class to ensure that the
+ref to scalar integer (holding the pointer) into that class to ensure that the
 DESTROY method will free the pointer and you never leak it, and your write
-method accesors using L<perlfunc/pack>, L<Win32::API/ReadMemory> and
+method accessors using L<perlfunc/pack>, L<Win32::API/ReadMemory> and
 L<Win32::API/WriteMemory> around the pointer.
 
 

Type.pm

@@ -412,7 +412,7 @@ LPHANDLE.
 =item signed char
 
 These 2 types by name force numeric handling. C<97> not C<"a">. C<UCHAR> is
-not a C<unsigned char> for numeric handling purposess.
+not a C<unsigned char> for numeric handling purposes.
 
 =back